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In This Guide 


The purpose of this guide is to describe how to design, develop 
and maintain a database using the Jasmine object database (ODB) 
system. It covers the stages of developing a Jasmine database, as 
well as the maintenance of existing databases. It is organized as 
follows: 


Chapter1 “Introduction” details the conventions used in presenting the 
information in this guide. Because they are vital to your 
understanding of this guide, it is highly recommended that you 
take the time to familiarize yourself with them. 


Chapter 2 “Introducing Jasmine” provides an overview of Jasmine, 
including its ODB system and the facilities it provides for 
database and application program implementation. 


Chapter 3 “Development Process” provides an overview of developing a 
Jasmine application. Included are descriptions of the various 
platforms on which you can base a Jasmine application and a 
summary of the tools available for your use. 


Chapter 4 “Object Database Concepts” describes the key object database 
concepts and provides some advice on the use of naming 
conventions. 

Chapter5 “Designing a Database” provides detailed advice and guidance 


on how to design a database. 
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Chapter 12 


Glossary 


Audience 


“Using ODQL” provides general information on how to use 
Object Database Query Language (ODQL). 


“Using Interpreted ODQL” gives information about how to use 
interpreted ODQL. It covers the use of both ODQL statements 
and ODQL interpreter commands, and includes information 
about transaction control and error handling. 


“Using Embedded ODQL” gives general information about 
embedded ODQL and information about how to use embedded 
ODQL in methods. 


“Setting up a Database” provides detailed instructions on how to 
define a database. 


“Populating a Database” explains how to load data into a 
database. It describes how to load small quantities of data, using 
the ODQL interpreter, and how to load larger quantities of data, 
using either the Jasmine load utility or your own load program. 


“Modifying the Structure of a Database” explains how to change 
the structure of an existing database using ODQL. 


“Performance Tuning” describes some of the factors that the 
developer should take into account to ensure that performance 
requirements are met. 


The “Glossary” provides an alphabetical list of commonly used 
terms with their definitions. 


This guide is intended to be used by application developers and 
database designers. 
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What You Need to Know 


Conventions 


Case-Sensitivity 


Cross References 


Key Names 


This guide assumes some previous knowledge of database 
systems in general, but not necessarily object database systems. 


This guide employs several conventions, described in this 
section, to make locating and identifying information easier. 


All class, command, directive, environment parameter, function, 
macro, method, and property names mentioned in this guide are 
case-sensitive. Therefore, the names must be spelled exactly as 
shown. System command and environment variable names may 
also be case-sensitive, depending on the requirements of your 
operating system. 


The following conventions are used to refer to information in 
another part of the documentation set: 
=» Guide name in italic: 

See the Getting Started guide. 
= Chapter name in double quotes: 

See “Application Development” in the Getting Started guide. 
= Section name as it appears in the document: 

See the Using Procedures section. 
The names of keys, such as Enter, Ctrl, and Del, appear in the 
document as they do on your keyboard, where possible. When 
referring to the four arrow keys as a group, they are referred to 
as Direction keys; however, the name of each Direction key (for 


example, Up arrow or Left arrow) is used when referring to them 
individually. 
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Conventions 


Key Combinations 


Key Sequences 


Syntax and User Input 


Whenever two keys are joined together with a plus (+) sign (for 
example, Ctrl+R), you should hold down the first key while 
pressing the second key to complete the command. Release the 
second key first. 


When keys are separated by a comma (,), press them in the 
sequence indicated. The keystroke sequence AIt+E, C, for 
example, indicates that you should hold the Alt key down while 
pressing the E key, release them both, then press and release the 
C key. 


When representing syntax and user input, the following 
conventions are used: 


Convention Usage 


Boldface Indicates keywords, symbols, or 
punctuation that you must type as shown 


Italic Indicates a variable name or placeholder 
for which you must supply an actual 
value—this convention is used in 
explanatory text, as well as syntax 


> Indicates results displayed by the system 
For example, you might be instructed to enter: 

d:\install 

The “d” portion is in italic, indicating a placeholder that you 
must replace with a value that makes sense in your own system. 
The “:\install” portion is in bold, so you enter it exactly as 
shown. 


For this instruction, you would type something like this: 


c:\install 
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2 Intoducing J asmine 


In This Chapter 


This chapter provides an overview of Jasmine, including its 
object database (ODB) system and the facilities it provides for 
database and application program implementation. 


Main Features 


Jasmine’s main features include: 
# Modeling complex information 


Jasmine is designed to handle data that is complex and of 
high value. It can, for example, handle data that is too 
complex or too variable to represent naturally in tabular 
form, as in a relational database system. 


=» Combined data access and object-oriented programming 


Jasmine’s object-oriented database acts as a repository for 
defining, administering, and concurrently accessing class 
definitions and objects. The Jasmine database supports 
complex data structures and large data volumes, as well as 
multiple inheritance, instance- and class-level properties and 
methods, and native support for collections and 
collection-level methods. 
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Main Features 


The Object Database Query Language (ODQL) provides 
complete database access including data definition, data 
access, and method writing. ODQL supports all of the 
capabilities common to modern object-oriented languages 
and can be used alone or in combination with a host 
language such as C or C++. 


Interfaces with C and C++ 


In addition to ODQL, Jasmine provides interfaces that allow 
you to write code in C and C++. ODQL statements can be 
directly embedded in C or C++ for writing methods or 
executed via the Jasmine C API. ODQL code can also 
communicate with modules written in other languages using 
C calling conventions. 


Multimedia and ActiveX structured storage support 


The multimedia class library defines classes for managing 
multimedia data. It contains classes with definitions for 
many types of common multimedia objects, like video, 
audio, and pictures, and several supporting classes for 
tracking copyright and other legal information regarding the 
data. In addition, there are classes conforming to the 
ActiveX Compound Document Architecture that can be used 
to present multimedia data to applications as a standard 
ActiveX structured store. 


ActiveX support 


The Jasmine ActiveX control and code component open the 
Jasmine database to systems, such as Visual Basic, that 
support these standard protocols. The ActiveX code 
component provides developers with a way to manipulate 
objects and collections stored in the Jasmine database by 
implementing Automation objects and collections. The 
Jasmine ActiveX control connects an application to a Jasmine 
database, providing session management, query running, 
and schema metadata access. 


Distributed client/server architecture 


Jasmine uses a client/server software architecture. The 
client/server implementation allows one server to support 
multiple databases, and each client can access multiple 
databases on many servers. 
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Main Features 


Your Jasmine applications execute on client workstations, 
either as stand-alone applications or as plug-ins to Web 
browsers, such as Netscape Navigator. Jasmine applications 
communicate with the Jasmine database server which 
executes business logic and provides the storage for 
multimedia objects and other data in your applications. 


- Stand-alone Jasmine applications communicate with the 
Jasmine server through any communications protocol 
available. 


— Jasmine Web browser plug-ins are used as applets 
within an HTML page—plug-ins use HTTP for 
communication with the Jasmine server that is optimized 
for incremental download. 


— The WebLink tool provides an easy way to access the 
Jasmine database across the Internet using HTML pages. 
You can use Jasmine to exploit the countless 
opportunities to integrate the Internet (or your 
company’s Intranet) with a broad array of business 
strategies, functions, and technologies. 


Database integration 


Jasmine provides complete integration with and support for 
other databases, including relational databases such as 
OpentIngres, Oracle, Sybase, Informix, and SQLServer. 


Data management services 


Jasmine provides a complete set of data management 
services that allow developers to concentrate on the 
functionality of their applications, including: 


- Locking and concurrency control 
— Transaction management 
— Recovery 


— Access control 
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Users of J asmine 


The users of Jasmine include: 


System administrator 


Someone who manages a Jasmine system, performing the 
role of service provider. The system administrator’s 
responsibilities include: 


— Resource and capacity planning 


-— Assembly of the various components (an issued 
application, the Jasmine issued software, the platform 
and network on which the software runs and file 
resources) 


- Day-to-day management of performance and 
availability, and monitoring of service levels 


The system administrator may or may not be the same as the 
administrator of the platform itself, depending on the scope 
of the Jasmine system. 


Developer 


Someone who is responsible for analyzing user and 
enterprise requirements, as well as designing and 
implementing a Jasmine database and application programs 
to meet those requirements. The developer is also 
responsible for validating that the database and application 
programs meet those requirements, and for handing them 
over to the system administrator for installation. 


Application user 


Someone who uses applications developed using Jasmine. 


This guide is aimed mainly at developers. 
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Design and Development Facilities 


ODQL Facilities 


Jasmine provides a number of facilities for designing, building, 
and testing databases and also for using and modifying them. 
There are also facilities for implementing user-defined 
application programs. 


ODQL is a complete database programming language that 
provides a number of general purpose programming facilities 
including: 


= Constructs to declare variables, assign values to variables, 
and use variables in expressions 


= Conditional execution 


« Iteration, either by a conventional while statement or by 
scanning the elements of a collection 


You can use ODQL not only in application programs written 
using the C API, but also in methods used to implement database 
operations. If necessary, you can also mix ODQL code with code 
in a host language such as C and C++ (for example, to invoke 
host language library routines or system programming 
interfaces). 


ODQL is available in the following environments: 
=» ODQL interpreter 


This is an interactive environment that allows you to either 
enter ODQL statements directly at the terminal or execute 
them from a file. The interpreter can be executed from the 
Jasmine server or from a client. 


=» ODQL preprocessor 


This allows you to embed ODQL statements in a host 
language and is used for writing methods. You can compile 
static ODQL for those parts that are unlikely to change. The 
preprocessor also allows you to construct dynamic ODQL 
statements at runtime. 
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Class Libraries 


» CAPI 


This lets you create full-featured ODB applications capable 
of running on client and server alike. This API provides 
direct ODB access through a function that executes ODQL 
statements and commands. ODQL variable access is 
provided through two functions that let you set and get the 
value of variables, while several functions allow you to 
manipulate the various ODQL data types. 


Jasmine provides a set of system classes for the basic data types, 
which include strings, dates, and various numeric types. The 
system classes also provide native support for various kinds of 
collections and for system management, such as transaction and 
session control. 


The system class hierarchy also provides the Composite class, 
which is used as the base class for all user-defined classes. 
Jasmine comes packaged with several class libraries based on this 
architecture, including a full-featured multimedia library. You 
can either use the classes as they are issued or specialize them 
using standard inheritance mechanisms. 


Application Development Environment 


Jasmine’s application development environment (Jasmine 
Studio) is a Windows application with an easy-to-use Graphical 
User Interface (GUI) that allows you to create Jasmine 
applications—without requiring extensive programming 
experience. From Jasmine Studio’s various inspector and editor 
windows, you drag database classes, objects, and other 
components onto application scenes (pages), then specify 
properties and behaviors for the objects in each scene. 
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Design and Development Facilities 


Jasmine Studio allows you to build Jasmine applications visually 
rather than programmatically as with the C API—when you use 
Jasmine Studio, underlying application code is hidden from 
view. Using Jasmine Studio, you can design, prototype, debug, 
and deploy multimedia Jasmine database applications and 
manage your database classes from an easy-to-use drag-and- 
drop interface. 
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In This Chapter 


This chapter provides an overview of developing a Jasmine 
application. Included are descriptions of the various platforms 
on which you can base a Jasmine application and a summary of 
the tools available for your use. 


Development Platforms 


In Jasmine, there are several approaches you can take to 
application development, depending on the type of application. 
Some of the types of applications you can develop using Jasmine 
are: 


« A full-featured application, with state-of-the-art multimedia 
interface, designed for distributing to end users with various 
interests, goals, and ranges of computer know-how 


«» Asimple interface to the Jasmine database using HTML 
pages that performs basic queries on and updates to a 
Jasmine database 


« A Visual Basic application that connects to a Jasmine 
database via a custom control implemented using the 
standard ActiveX protocol 


» A utility or class library to be used by other Jasmine 
developers 
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Development Platforms 


=» An ad hoc query or one-time program to modify a Jasmine 
database, such as an initial data load or a change to a class 
definition 


In order to let you do all these things, and more, Jasmine 
provides various platforms for application development. 


Jasmine Studio For most applications, Jasmine Studio will be the primary choice 
of development platform, simply because it gives you so many 
options and features an integrated development environment 
with an easy to use graphical interface. 


Jasmine Studio is the recommended environment for developing 
multimedia applications, whether the resulting application will 
run stand-alone or as a Web browser plug-in. It also provides 
useful tools for building class libraries, allowing you to define 
classes and methods and view the class hierarchy in a graphical 
form. 


C API The C API is a versatile tool that gives you access to a Jasmine 
database via ODQL statements executed using a C function call. 
ODQL variable access is provided through functions that let you 
set and get the value of variables, while several functions allow 
you to manipulate the various ODQL data types. 


Some of the other Jasmine tools (for example, Jasmine Studio) 
use the C API in their implementation, but many Jasmine 
developers will never need to use the C API directly. Its main 
intent is for developers who want to develop utilities and tools 
for use with Jasmine. 


ActiveX Control and The Jasmine ActiveX control and code component open the 

Code Component Jasmine database to systems, such as Visual Basic, that support 
these standard protocols. Developers can, for example, create a 
query in Jasmine Studio’s Query Editor or using the C API, then 
run the query in the Jasmine ActiveX control. 


The ActiveX control invokes the Jasmine code component to 
return the objects to the host language (such as Visual Basic), 
where the objects can be subsequently manipulated. These 
objects interact with the code component to work with objects, 
methods, and properties in a Jasmine application. 
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WebLink WebLink provides access to the Jasmine database across the 
Internet (or your company’s Intranet) using HTML pages. 


ODQL Interpreter The ODQL interpreter provides an interpretive environment for 
executing dynamic ODQL statements entered from the terminal 
or from a file. As an interactive environment, it is useful for 
testing ideas, debugging methods, and exploring the contents of 
your database using ad hoc queries. 


The ODQL interpreter is also invaluable when used in batch 
mode as a way of executing files of ODQL. This might be to 
build the database, to compile the methods, to upgrade to a new 
version of the application, or to populate the database with data. 


When using Jasmine for the purpose of application development, 
you can choose from all the available platforms. Some 
developers may find that a single platform, such as Jasmine 
Studio, suits all their needs, while others may find a combination 
more suitable. 


Application versus Database 


The term application refers to the programs that access a Jasmine 
database and to the database itself. The database resides on the 
Jasmine server and acts as a repository for the class and method 
definitions, and for the objects, or data, defined using those 
classes. The application programs, on the other hand, usually 
reside on the Jasmine client and access a database on the server— 
which may or may not reside on the same machine as the client. 


The remaining chapters in this guide address the application 
from the point of view of the database, including using the 
ODQL interpreter for accomplishing various tasks. To get 
detailed information on developing application programs using 
any of the other development platforms, refer to other parts of 
the Jasmine documentation set using the summary found in the 
“Introducing Jasmine” chapter of the Getting Started guide. 
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4 Object Database Concepts 


In This Chapter 


This chapter describes key object database concepts and provides 
some advice on the use of naming conventions. The illustration 
below shows how the concepts described in this chapter relate to 
each other: 
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For further information about the concepts described in this 
chapter, refer to the Reference guide. 


Stores are the containers in which data is held within Jasmine. A 
store is divided into extents, each of which is associated with one 
or more files. Stores contain both metadata (class, attribute, and 
operation definitions) and user data. You can have any number 
of stores open at once. 


There are four types of stores, listed below. Of these, only user 
stores and the system store are accessed directly by user-written 
applications. 


= System store 


A store used by the system to store Jasmine system classes. 
The system store is created when Jasmine is installed. It is 
updated automatically with information about user stores 
and class families. You can choose to store your 
user-defined class families in the system store or create a 
user store for that purpose. 


= User store 


A store for storing user objects—for example, Persons, Projects, 
and Locations. A number of user stores can exist within a 
system. Stores can be created and deleted at any time, 
though in most cases they will be established permanently 
by the system administrator. 


= Work store 


A store used by the system as a place for the temporary 
storage of information during a Jasmine session. For 
example, if you issue a query that finds 10,000 objects and 
you assign the result to a collection-valued variable, the 
value of the collection-variable is stored in the work store. 
The work store is created when a session starts and is deleted 
when this session ends. 


Class Families 


= ‘Transaction store 


A store used by the system for storing temporary 
information regarding collections used during a transaction. 
The transaction store is created when a session starts, and is 
deleted when a session ends. 


The system store and all user stores go together to make up the 
database. 


Class Families 


A class family consists of a collection of related classes (see 
Classes later in this chapter). Class names are unique within 
each class family. Typically, different class families will be 
developed by different people, perhaps in different 
organizations, so it is possible for two unrelated classes in 
different class families to have the same name. For this reason 
class names in applications can always be qualified by a class 
family name. 


A class family will often be the unit of re-use: class families can 
be written to be usable in a wide range of applications. 


Provided there are no conflicts between the class names, it is 
possible to merge two class families into one. This is achieved 
using the unload and load utilities. The multimedia class family, 
for example, is issued with the Jasmine product in the form of an 
unload file, and can be merged with a user-written class family 
using the load utility. 


A store can hold several class families. The store and the class 


family are further distinguished because one is a physical 
concept and the other is logical. 
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The classes in a class family are arranged in a hierarchical 
relationship, forming a tree, or a set of trees, within the overall 
class hierarchy. A class cannot inherit from a class in a different 
user-defined class family; it can only inherit from another class in 
the same class family or, in the case of classes at the top of a 
hierarchy of user-defined classes, from the system class called 
Composite (see Classes later in this chapter). A class that inherits 
directly from Composite is sometimes called a top-level class. 
There must be at least one top-level class in a class family, but 
there can be several. 


Although classes can only inherit from other classes in the same 
class family, other relationships can cross the boundaries 
between class families. For example, the properties of a class can 
reference objects of any other class, and the methods of one class 
can take parameters and declare variables of any other class. 


A class is a collection of objects with common features. Objects 
can be categorized into classes which define the common 
features of real-world entities, which are themselves represented 
in Jasmine as instances of the class (see Instances later in this 
chapter). Each class has a name which is used to distinguish it 
from other classes. 


For example, a company might have people based at a number of 
locations. Location is, therefore, a class, and the individual 
locations such as New York, Paris, and Tokyo are its instances. 
The instances of a class can be represented in tabular form, as 
shown in the following example: 


Classes 


Location class 


New York | 5555 7" Avenue +1-222-333-4444 
1 Avenue de |'Europe —_ +33-1-34-65-80-70 }2s3 [ages 86 


Dublin South County +353-1-2956644 -6.25 53.33 
Business Park, 
Leopardstown 

Tokyo 1015, Kamikodanaka, +81-44-754-3318 139.75 35.67 
Nakahara-Ku 


Some system-defined classes are provided with Jasmine to cover 
the basic object types, such as Integer and String, as well as 
internal object types, such as Session and Transaction. Users can 
define the additional classes they need for their data as 
user-defined classes. 
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The system-defined classes are organized into a class hierarchy 


as illustrated below: 


Object 
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Property 


An example of a hierarchy for a user-defined class appears in 
Defining the Class Hierarchy in the “Designing a Database” 
chapter. In addition, you can refer to the Class Reference 
Supplement for the class hierarchies of the Jasmine supplemental 
libraries, such as the multimedia class library. 


New classes always inherit from an existing class, which means 
that each class always has at least one superclass in the class 
hierarchy. The classes at the top of a hierarchy of user-defined 
classes have the system class Composite as their superclass. 


4-6 Using Jasmine 


Instances 


Instances 


Classes can be of either of the following types: 
« Literals 


These are simple values such as numbers and character 
strings. Jasmine supports two kinds of literals: atomic literals, 
which can be integer, decimal and so on, and user-defined 
tuples, which are structured values having a number of 
named components. Literals exist in Jasmine only as the 
values of properties or variables; they have no independent 
existence of their own. 


= Entities 


These exist in the database and have object identifiers. 
Entities exist from the time they are explicitly created (for 
example, by the new() operation) to the time they are 
explicitly deleted (for example, by the delete() operation). 
The object identifier does not change during the life of the 
entity and is never reused to refer to a different entity. 
Entities can be divided into system entities, such as Session 
and Transaction, and user entities, which are classes 
subordinate to the system class Composite. 


Note: Classes in a supplemental class library, such as the 
multimedia class family, are typically implemented as user 
entities. 


The instances of a class typically represent the individual 
real-world objects represented in the database. Each real-world 
object for which you need to store information is handled as an 
instance of a particular class. Although all the instances in a class 
share the same set of properties, the values of those properties 
are, in general, different for each instance. For example, as 
shown below, the instances in the class Person share the property 
names, grade and phone, but the value of each of these 
properties varies according to the individual instance. 
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name grade | phone 
Instance >| John Brown 12 2468 
Instance >|Jane Jones 2 9292 
Instance >| Fred Smith 6 4888 


Properties 


The information held about instances of a class is defined as a set 
of properties. As shown below, a property can either store a 
single item of information, such as an employee’s date of birth, 
or a collection of items of information of the same type, such as 
the collection of programming languages in which a programmer 
has experience: 


Single Single Single Multi- 
valued valued valued valued 
property property —_ property property 
VY VY on VY 


Programming 
languages 


One value is John Brown 


stored in one 


property 

A number of 
values are stored 
in one property 
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Instance-Level and Class-Level Properties 


You can define properties as either of the following: 
« Instance-level properties 


This is the normal case. An instance-level property has a 
different value (in general) for each instance of the class. For 
example, each location has its own name, its own phone 
number, and its own latitude and longitude. 


= Class-level properties 


By contrast, a class-level property has a value that applies to 
the class as a whole. For example, if all employees have the 
same retirement age, then retirement age might be defined as 
a class-level property of employee. 


Of course, if this were a constant for all time and for all 
employees, there would be no point in putting it in the 
database. Class-level properties can be useful, however, 
where the value might change with time or where a value 
might be different for different subclasses. For example, 
salaried employees might have a different retirement date 
from hourly employees. 


Class-level properties are often used as input to the methods 


associated with a class. 


The illustration below shows the difference between 
instance-level and class-level properties: 


Instance-  Instance- Class- 
level level level 


property property property 


The same value 
John Brown is stored for all 
instances in the class 


A different value 
is stored for eac 
instance 


J Fred Smith 


Jane Jones 
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Missing Properties 


In both cases, properties can be one of two types: 


Attributes 


These are items of raw data, such as a name, a number, or 
collection of names or numbers. The value of an attribute is 
either an atomic literal or a collection of atomic literals (see 
Atomic Literals later in this chapter). 


Relationships 


The value of a relationship is, in most cases, a reference to 
another entity or a collection of entities. For example, a 
Person might have a property called boss, which is a 
reference to another Person, while a Project might have a 
property staff, which is a reference to a collection of Persons 
who work on that project. 


Typically, a relationship identified during requirements 
analysis might result in a pair of Jasmine relationships, one 
in each direction. The various ways of implementing 
relationships are discussed in the “Designing a Database” 
chapter. 


A property can be declared as mandatory, in which case it must 
always be given a value. If a property is mandatory for one 
class, then it will also be mandatory for all its subordinate 
classes. 


A property can also be given a default value; this value is used 
when an object is newly created if no other value is supplied. 


A property that is not mandatory can be NIL. NIL is not a value; 
it is the state of a property that currently has no value. There can 
be various reasons for this—for example, the value might not be 
known or it might not be applicable in this case. 
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Atomic Literals 


Properties 


For a property to be NIL is not the same as having a value of 
zero, or a character string that is all spaces, or any other value. 
For collection-valued properties, being NIL is not the same as 
being empty, which is represented as Bag}{}, List{}, or Set{}, 
depending on the kind of collection. For example, if the 
collection-valued property children is empty, we know that the 
person has no children; while if it is NIL, we do not know 
whether the person has any children or not. 


Properties can be changed at any time to make them mandatory 
or non-mandatory. If a property is made mandatory, it must 
already have a value in all existing instances. 


A property can be specified as unique over all instances of a 
class. The constraint of uniqueness can be applied to both new 
and existing properties and can be removed from existing 
properties to which it has previously been applied. 


Uniqueness is inherited and cannot be overridden in subclasses. 
For example, if the property PersonnelNo of the class Employee 
is declared unique and Manager is a subclass of Employee, then 
all employees, including managers, must have distinct personnel 
numbers. 


Uniqueness can apply to any single-valued property, including 
attributes and relationships. 


Defining a property as unique does not automatically create an 
index. If the property needs an index, you must add the index 
explicitly. 


Ultimately, all information in Jasmine is held in the form of 
atomic literals. The types of literals supported in Jasmine are 
shown below: 
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Type 
Boolean 


ByteSequence 


Date08/14/98 


Allowed Values 

Logical value (TRUE or FALSE) 
Variable-length byte string (up to 65,536 bytes) 
A maximum length can be specified if required. 
Date value, including month, day, year, and era 


Valid dates are within the range of January 1, 
1582 to December 31, 2382. 


Decimal 


Integer 


A fixed-point number with p decimal digits, of 
which q are after the decimal point 


p is from 1 through 18, g is from 0 through p. 
Integer from -2,147,483,648 to 2,147,483,647 


Real 


A floating-point number in the range 
+/-4.941e-324 to +/-1.797e+308 


The smallest allowable positive value is 
+4.941e-324, and the largest negative value is 
-4.941e-324. The maximum precision for Real 
values is around 15 decimal digits. A number 
with an absolute value less than 2.226e-308 may 
have less precision and can be obtained only as 
the result of an arithmetic operation—it cannot 
be specified as a constant. 


String 


Variable-length character string (up to 65,535 
bytes) 


A maximum length can be specified, if 
required. 


One of the things that most strongly distinguishes an object 
database from other technologies is that the database can be 
used, not only to store and retrieve information, but also to 
process it. This is done through methods. 
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Methods 


Methods are typically used: 


= To calculate derived data (for example, price including tax 
from price excluding tax) 


=» To maintain redundant data (for example, control totals or 
bi-directional relationships) 


= To access information held externally to Jasmine (for 
example, in a relational database or a document database) 


= To hide the details of how information is represented 
internally 


Example of a Method 


An example of a situation in which you could use a method is 
one where each person in an organization might be allowed to 
incur expenditure up to some agreed limit. The spendingLimit() 
method is used to determine what that limit is for each 
individual. 


The programmer or user wanting to retrieve this information 
does not need to know how the spending limit is calculated. At 
one extreme it might be stored separately for each employee; at 
the other extreme it might be a constant for the whole database. 
Or it might be calculated from other data, such as the employee’s 
grade. The user of the method only needs to know its name and 
specification. It can then be used in a query. 


For example, this code fragment retrieves all persons whose 
spending limit exceeds 100.00: 
Bag<Person> pp; 


pp = Person from Person 
where Person.spendingLimit() > 100.00; 


The method spendingLimit() can be used anywhere a property 
could be referenced, but unlike a property, there is no stored 
data: the value is calculated on demand. 
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You write the algorithm—that is, the code of the method—using 
some combination of a host language (C or C++) and Jasmine’s 
native database programming language, ODQL. Typically, you 
will use the host language for any complex computations and for 
access to the external environment, while you will use ODQL to 
access the Jasmine database. 


Although the host language and ODQL can always be used in 
combination, it is quite common for a method to be written 
entirely in the host language or entirely in ODQL. For further 
information about the use of ODQL, see the “Using ODQL” 
chapter. 


The example below is code to calculate spending limit as a 
simple function of a person’s grade. This example is written 
entirely in ODQL, as indicated by the $ signs at the start of each 
statement: 


defineProcedure Decimal [8,2] 
Person: :instance: spendingLimit () 


$if (self.grade < 10) { 
$return (25.00); 


}; 
$return (100.00); 
}; 


Here: 
= defineProcedure identifies this as a method definition 


=» Decimal [8, 2] indicates that the result of the method is a 
decimal value with precision 8, scale 2 


= Person::instance indicates that the method applies to an 
instance of the Person class 


= spendingLimit() is the name of the method, which has no 
parameters 


« The $ signs identify ODQL statements 


«  self.grade is a reference to the grade property of the person 
whose spending limit is currently being calculated 


=» The return statement indicates exit from the method witha 
given return value 
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Methods 


Methods can be defined at different levels, according to the 
objects they act upon: 


Instance-level methods 


An instance-level method operates on an individual instance 
of aclass. For example, the method spendingLimit() 
operates on an individual person. The method is the same 
for all instances of Person, but it is only applied to one 
person at a time, returning a potentially different result for 
each person it is applied to. 


Class-level methods 


A class-level method operates on the class as a whole. 
Class-level methods are used when there is no identifiable 
instance to apply the method to. Examples are: 


— Methods that create a new instance of the class 


— Methods that look at all the instances of a class and give 
a particular instance, given certain information (for 
example, a method to find the location with a given 
name) 


— Methods to access the class definition itself (for example, 
to determine the subclasses of a class) 


Instance-collection-level methods 


An instance-collection-level method (often referred to simply 
as a collection-level method) operates on any collection of 
instances of the class. For example, there might be a method 
called coLocated() that, given any collection of persons, 
determines whether they are all based at the same location. 


Class-collection-level methods 


A class-collection-level method operates on a collection of 
classes. These are only encountered in rather specialized 
applications. An example might be a method which, given a 
collection of classes, determines their lowest common 
superior class. This is the lowest class in the class hierarchy 
of which all the given classes are subordinates. 
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Methods Provided by the System 


Jasmine provides a large number of system methods to help you 
to build applications efficiently. These are fully described in the 
Reference guide. The table below summarizes the methods 
available. For a complete list of available methods, refer to 
Appendix E of the Reference guide. 


Purpose Examples 


System control methods (for Transaction.start(), 
controlling transactions) Transaction.end(), 
Transaction.rollback() 


Managing instances new(), delete(), print() 


Managing collections average(), count(), max(), 
median(), min(), mode(), sum(), 
stdDeviation(), union(), 
intersect(), differ(), sort(), 
unique(), createlterator(), 
deletelterator(), hasElement(), 
hasSameElements(), hasSubset(), 


isSubset() 
Access to metadata getClass(), getClassName(), 
(information about classes) — getAlClasses(), 
getMethodSource() 
Modifying metadata (class | newClass(), addProperty(), 
definitions) addSuper() 
Tuning performance createIndex(), dropIndex() 


Inheritance 


Jasmine classes are organized into a class hierarchy that allows 
the natural relationships of generalization and specialization 
identified during analysis to be modeled directly in the database 
(see the class hierarchy chart in the Classes section earlier in this 
chapter). 
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When you define a class, you also define its superclass. The new 
class inherits the characteristics (properties and methods) 
defined for its superclass. Occasionally, you may want to define 
more than one superclass: this is called multiple inheritance. 


For example, when defining the class Manager, you define 
Person as its superclass. The new class Manager is said to be a 
subclass of Person. All the properties defined for Person, such as 
name, date of birth, and phone number, are automatically 
available for the new class Manager, too, as are the methods for 
Person, such as spendingLimit(). This applies to properties and 
methods, regardless of level. For example, class-level methods 
are inherited, as well as instance-level methods. 


Information 
inherited by 


Person class 
subclasses 


Spending 
Limit( ) 


Direct Programming | Boss 


Training 
reports languages 


Subclasses inherit Manager class Programmer class 
information from oO 
Superclasses 


Output of content 


Manager class 


Spending 
Limit( ) 


Throughout the Jasmine documentation, the following 
terminology is used when talking about the class hierarchy: 
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= Person is a superclass of Manager if Person is explicitly 
named as a superclass in the definition of the Manager class 


= Manager is a subclass of Person if Person is a superclass of 
Manager 


= The classes superior to Manager are its superclasses, their 
superclasses, and so on up to the top of the class hierarchy 


=s The classes subordinate to Person are its subclasses, their 
subclasses, and so on down to the bottom of the class 
hierarchy 


All user-defined classes are subordinate to the system-defined 
class called Composite. 


Refinement and Polymorphism 


Rather than simply inheriting characteristics in a subclass 
unchanged, it is possible to make certain alterations to the 
definition in the subclass. This is called refinement. Refinement is 
only allowed if the subclass still conforms to the superclass, that 
is, if it allows an instance of the subclass to be retrieved 
anywhere an instance of the superclass could be retrieved. The 
subclass, however, can be more restrictive as regards updates. 
The detailed rules are given in the Reference guide. 


In the case of methods, the refinement can provide completely 
different code to implement the same operation. An operation 
that is implemented in different ways for different classes is 
called polymorphic. When the operation is executed, the method 
chosen is the one for the specific class of object it is executed 
against. For example, requesting the operation spendingLimit() 
for a Manager executes code that knows how to calculate 
spending limit for managers, while requesting the same 
operation for Programmer executes code that has knowledge of 
programmers. 
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Multiple Inheritance 


Multiple inheritance occurs if a class has more than one 
superclass. When a class has more than one superclass, naming 
clashes can occur because the characteristics inherited from one 
superclass have the same names as those inherited from another. 
In such a case Jasmine reports an error, which can only be 
resolved by explicitly refining the characteristic in the subclass. 
In some cases, it may not even be possible to resolve the clash by 
refinement because of the rule that the parameters of methods of 
the subclass must conform to each of its superclasses. 


Naming Conventions 


Jasmine has a uniform naming system: the things that can be 
named include stores, class families, classes, properties, methods, 
parameters, and variables. 


Names are up to 32 bytes long, consisting of ASCII alphabetic 
letters (A-Z, a-z), digits (0-9), and the underscore character. 
Names cannot start with a digit. Names are case-sensitive (for 
example, XYZ and xyz are different names). 


You cannot use a name that is a reserved word. To allow future 
extensibility, Jasmine has reserved many of the words used in 
the SQL standards, as well as the keywords of ODQL itself. 
These words are listed in the Reference guide. If you want to use 
a reserved word as a name you can do so by writing it in single 
quotes. For example: 


‘description’ 
Additional naming conventions have been adopted for 


system-defined names and for examples used in this guide and 
in other related documents in the Jasmine documentation: 


= The separate words of names are run together, with no 
spaces or other separators between 


= The names of classes and class variables have initial upper 
case for each word (for example, Person or ByteSequence) 
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Abbreviations within the name are all capitals, for example 
MMStorageControl. 


= The names of characteristics (properties and operations) 
have initial lower case for the first word and initial capital 
letters for subsequent words (for example, projects or 
projectMembers) 


These conventions are not mandatory, but if you follow them in 
your own applications, they will help to achieve consistency. 


You might occasionally want to define a private property or 
method that is intended only for use within the methods of its 
class. Although you cannot enforce this, you can use a naming 
convention to signal that the property is not intended for public 
use (for example, by adding __X as a suffix to the name). 


Leading underscores should be avoided. This is because such 
names may clash with unpublished global symbols in various 
standard libraries, especially dynamic libraries. 


For further information on naming conventions, refer to the 
Reference guide. 
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Chapter 


5 Designing a Database 


In This Chapter 


This chapter provides detailed advice and guidance on how to 
design a database, covering the two main stages of the database 
design process: 


= Logical database design 
« Physical database design 


The illustration below summarizes the process: 


Logical database design 


Define the class hierarchy} 
Define the relationships } 


Physical database design 


Define the stores } 
Define the indexes ) 
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Logical Database Design 


Logical database design consists of the following steps: 


1. Identify the classes. 

2. Define the class hierarchy. 

3. Define the attributes. 

4. Define the relationships. 

5. Define the methods. 
Identifying the Classes 


You will already have identified the main business objects 
during the requirements capture. You now need to identify the 
Jasmine classes. The first step is to determine the extent to which 
it is possible to map each kind of business object to a class. 
Although it may be possible to achieve a direct mapping, in 
practice you will often find that you need to make considerable 
refinements to the list of classes at this stage. The refinements 
arise primarily from: 


Abstraction 


Decomposition 
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Using Abstraction 


Abstraction is the process, illustrated below, where you identify 
that two classes have something in common. For example, 
Manager and Programmer are both special cases of Person. 


Manager class Programmer class 


of birth languages training 


Collect all the information with common 
characteristics and put it into one class 


Person class 


a Relationship 
Name| Vate Phone 
Superclass of birth between 
classes 
a 


Direct All reports Programming Hardware Total 


Manages ae 
reports languages training 


Subclass 


Manager class Programmer class 


Manager and Programmer, therefore, become subclasses of 
Person, which is defined as the superclass for both. Information 
that is common to both Manager and Programmer—for example, 
name, date of birth, and telephone—can be combined and 
defined in the superclass Person. Manager and Programmer 
contain the more specific information not required at the 
superclass level. For example, Manager contains subordinates 
and Programmer contains programming languages. 
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Using Decomposition 
Decomposition is where you split an object up into multiple 


objects to represent its complex internal structure. For example, 
a Project includes a Plan, a Budget, and so on as follows: 


Plan 


Project >| _ Documentation 


Schedule 


The result of decomposition is to identify additional classes 
connected to the original classes by relationships. These will 
often be one-to-many relationships. The process of normalization, 
described in textbooks on data analysis, can then be used to 
decide which properties belong with which classes. 


Dealing with Typical Problems 
Some typical problems that arise during the class identification 
stage are: 
=» How much information should go in one object? 


=# How much normalization is appropriate in an object 
database? 
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Faced with the decision whether or not to split an object into two 
(for example, Project and Plan), the factors to take into account 
are: 


« Is the relationship between the two permanent or transient? 
If it is transient, make them separate objects. 
« Is the relationship one-to-one or one-to-many? 


If it is one-to-many, it is probably best to make them separate 
objects. 


Jasmine allows collection-valued attributes, so there are 
situations where an extra table would need to be introduced ina 
relational database, but where an extra class is not needed in 
Jasmine. For example, the collection of programming languages 
known to a particular programmer can be stored in one attribute 
of type collection-of-string. 


Over-reliance on collection-valued properties, however, can be 
dangerous because it reduces potential for change. If you later 
want to record not only the languages known to the 
programmer, but the years of experience or the weeks of training 
in each, this information cannot easily be added if you have used 
a collection-valued attribute. Although the programming 
languages known to a programmer could be represented as a 
collection of strings, the level of experience in each language 
would be harder to represent this way. 


Avoid the temptation to pack composite data into each element 
of the collection or to have several parallel collection-valued 
attributes. An example of the latter is a collection of strings 
representing the language and a parallel collection of integers 
representing the amount of experience in each. Such structures 
quickly become unmanageable. 
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Instead of using collection-valued attributes, it would be better to 
define a separate class called ProgrammingKnowledge and 
define a relationship between Programmer and 
ProgrammingKnowledge as shown below. There would be one 
instance of ProgrammingKnowledge for each language known to 
each programmer. It would then be straightforward to add extra 
attributes to this class. 


ProgrammingKnowledge 


Programmer . N Language 
Years Experience 
Weeks Training 


If information about the languages known to a programmer is 
always obtained through methods, then the way it is stored 
internally can be changed over time by rewriting the methods 
without affecting the interface. 


Defining the Class Hierarchy 


The classes within the application need to be organized into a 
class hierarchy which represents the natural relationships of 
specialization and generalization. 


Some of the things you need to consider when defining the class 
hierarchy are: 

« The inclusion principle 

= How to take advantage of polymorphism 

= Avoiding the need for instance migration 

« When to use multiple inheritance 

» Avoiding multiple inheritance ambiguities 

«» Avoiding system limits 


= Reusing existing classes 
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The Inclusion Princ iple 


If you are familiar with object-oriented programming, you may 
be aware that there are two ways of exploiting inheritance. One 
way is to reflect an “is-a” relationship: a manager “is a” person, 
so the class Manager inherits the characteristics of the Person 
class. This is called inclusion inheritance. 


The other way is to reflect a reuse relationship. For example, the 
Customer class has an address formatting method, and you need 
an address formatting method for the new class Employee, so 
you make Employee inherit from Customer. However, there is 
no “is-a” relationship here; it is not true that every employee “is 
a” customer. 


The class hierarchy in Jasmine should only be used where there 
is a genuine inclusion relationship. Never use it to achieve ad 
hoc reuse. This is because Jasmine—unlike object programming 
languages—supports concepts such as queries, grouping 
expressions, and constraints, which apply across all the instances 
of a class and, by default, the instances of a class are taken to 
include the instances of its subclasses. 


You can check that you are following this rule by applying the 
“is-a” test. If you want to make X a subclass of Y, always ask 
yourself whether it is true that every X is a Y. 


Taking Advantage of Polymorphism 


An operation is polymorphic if it is implemented in different 
ways for different classes of object. For example, the operation 
spendingLimit() is polymorphic if there are different 
spendingLimit() methods for Manager and for Programmer. 


Polymorphism is one of the main strengths of object technology 
because it gives potential for change. Instead of enumerating all 
the possible cases in complex conditional code in one algorithm, 
you write separate code for each class of objects. When new 
classes are introduced to the system, you do not have to modify 
the complex existing code; you just add new methods to cater to 
the new class. 
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To exploit polymorphism, you may want to identify subclasses 
of a class even though all the subclasses have the same visible 
characteristics. For example, you may want to identify 
USLocation as a subclass of Location, not because you are 
keeping different information about US locations, but because 
you want to use a more elaborate address validation routine that 
accesses a US geographical database. If you do this, however, 
beware of introducing classes that are visible to users but 
meaningful only to the system designers. 


You can get the full benefit of polymorphism only if you get the 
class hierarchy right. Sometimes this can mean anticipating 
future change, perhaps introducing a level into the class 
hierarchy that is not needed now, but could prove useful later. 
For example you might recognize that some of the methods you 
are writing for Person would be applicable whether or not the 
person is an employee, while others are appropriate only to an 
employee. Even though your system is currently designed to 
deal only with employees, it might be sensible to introduce the 
two classes, Person and Employee, and divide the methods 
accordingly. This gives better scope to extend the class hierarchy 
and use polymorphic methods later on. 


Avoiding the Need for Instance Migration 


If you define a very fine-grained class hierarchy, you will 
encounter the problem that an object sometimes needs to change 
its class. This can happen quite naturally in the life-cycle of the 
object—for example, a programmer may at some stage become a 
manager. 


Jasmine, like most object systems, does not allow an object to 
change its class; so if this situation arises, you will have to create 
anew manager object, copy all the relevant data across, update 
any affected relationships, and then delete the programmer 
object. 
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This is manageable if it only happens occasionally, but you 
should design the class hierarchy so that it is not a frequent 
event. Otherwise, you will lose the benefit of having stable 
object identifiers. For example, it would be a mistake to make 
OverdueProject a subclass of Project because a given project 
might frequently change from one status to the other and back 
again. 


Tip: If your reason for defining OverdueProject as a separate 
class is that you want to maintain extra information for 
overdue projects, an alternative is to define these properties 
for all projects, and let them be NIL in the case of projects 
that are not overdue. NIL values have a very low space 
overhead in Jasmine. 


When to Use Multiple Inheritance 


Some experts advise you to never use multiple inheritance on the 
grounds that the problems can be greater than the benefits. 
Certainly it should be used with some care. 


Multiple inheritance arises naturally when you have two 
orthogonal classifications of the same objects. For example, you 
can classify people as male or female, adults and children. Then 
you could construct the class hierarchy shown below: 


Person——————__ MalePerson-——_—___ MaleAdult 
FemalePerson FemaleAdult 
Adult MaleChild 
Child FemaleChild 


The classes at the top two levels on this diagram would be 
abstract classes; that is, they would contain definitions of 
properties and methods but would have no immediate instances. 
All the instances would belong to one of the four classes at the 
bottom level (for example, MaleChild). 
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The danger of this approach is that it can become unmanageable. 
The number of classes can multiply very quickly, and it can 
become very difficult to test all possible interactions of different 
polymorphic methods. 


Before using multiple inheritance, ask yourself some searching 
questions: 


=» Doyou really need such fine-grained classifications? Do 
adults and children, for example, really have to be separate 
classes? Can you represent the information adequately using 
attributes? 


» Are you sure that all the inheritance links follow the 
inclusion principle? 


It can be very tempting to use multiple inheritance to 
represent a whole-part relationship. For example, a vehicle 
has an engine and a chassis, so it has all the characteristics of 
an engine and a chassis; therefore, we will make it inherit 
from engine and from chassis. However, a vehicle is neither 
an engine nor a chassis, so this breaks the inclusion principle. 
You need to use relationships instead. 


= Is the classification stable? 


The problem of objects changing their class can be 
particularly acute if you use a very fine-grained classification 
with multiple inheritance. 


The cases where multiple inheritance is useful are where there is 
a genuine overlap of categories that are otherwise quite distinct. 
Products and documents are separate things with quite different 
characteristics, but there can also be documents that are sold as 
products in their own right and that have all the characteristics of 
a document and all the characteristics of a product. 
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Avoiding Multiple Inheritance Ambiguities 


Where you do use multiple inheritance, the danger arises that 
several superclasses have properties or methods with the same 
name. If this situation arises, Jasmine insists that you identify 
which property or method you want to inherit by means of a 
refinement. The refinement must be consistent with both the 
superclasses so that, if there is a clash, then multiple inheritance 
may not be possible. For example, if the class Document has a 
method display() that takes no parameters and Product has a 
method display() that takes one parameter, then it will not be 
possible to produce a refinement of display() that conforms to 
both superclasses. 


The problem can largely be avoided by: 


= Avoiding inappropriate use of multiple inheritance 


(See When to Use Multiple Inheritance earlier in this 
chapter.) 


= Choosing sensible names for properties and operations that 
reflect their true meaning 


Avoid names like “status” and “code” that could mean 
anything. 


Avoiding System Limits 


Jasmine does have limits on the number of classes in the system 
and on the number of subclasses for any class. These limits are 
very high, and you are only likely to hit them if you are using the 
system in a way it was not designed to be used. 
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For example, suppose you have an engineering database in 
which you want to model different parts. If you want to model 
different types of parts (gaskets, camshafts, widgets, and so on) 
and also individual instances of each type of part (camshaft serial 
number 100003, and so on), then you might be tempted to have 
Gasket, Camshaft, and so on as subclasses of the class Part. The 
fact that Jasmine allows you to create classes at any time makes 
this quite feasible. But if you have tens of thousands of different 
types of parts, you would rapidly exceed system limits. Your 
application would also become extremely inefficient, because a 
query on parts would have to scan so many different small 
collections of instances. 


Tip: There are some cases—where the number of subclasses 
is a few hundred—that are not quite as extreme as this but 
still require careful treatment. One useful device in such 
cases can be to increase the number of layers in the class 
hierarchy, so instead of a class having 400 subclasses it has 
20 subclasses each with 20 subclasses of its own. However, if 
the design comes anywhere near these numbers, it is worth 
asking whether this is really the best way of modeling the 
data. 


Grouping Classes into Class Families 


There are two ways to define class families: 


=» You can do it as the first stage in defining the modularity of 
the application, so that different parts of the system can be 
handed over to different developers for detailed design. 


For example, you might decide early on that one part of the 
application is concerned with publishing of documents and 
another part with billing, and allocate these to separate 
teams before any of the classes are defined in detail. 


« Alternatively, you can design the complete class hierarchy 
and then work out the best way of dividing it up into a 
number of class families. 
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Logically, it makes very little difference which classes are in 
which class family, provided that you adhere to the constraints 
(see the “Object Database Concepts” chapter for further details). 
Class families should be used mainly to split the application into 
convenient units to allow developers to work in parallel. 


In practice, however, the needs of physical database design can 
impose some additional constraints. These are discussed later in 
this chapter. 


Tip: One constraint is that if you want to have your database 
physically partitioned into a number of separate stores, you 
cannot have a single user-defined class from which all your 
other classes inherit; there must be one such class for each 
class family. If you want shared behavior for all your 
classes, you can achieve this by making a copy of your 
top-level class and putting it at the top of each class family. 


Reusing Existing Classes 


An important benefit of object technology is the ability to reuse 
classes that already exist. You should always look for 
opportunities to do this when designing your own classes. 


The classes you reuse might come from your own project, or 
from other projects within your own organization. They might 
come supplied with the Jasmine product, such as the multimedia 
class family, or from third parties. 


There are several ways to take advantage of an existing class 
definition: 
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Define a subclass of the existing class 


This is one of the best techniques, because it allows you to 
take advantage of improvements in the classes you are 
reusing when they become available. For example, you can 
define your own subclass of the multimedia class, Content, 
to handle a media format that the supplied classes do not 
handle. This will reuse all the functionality concerned with 
managing internal large objects, but you will have to define 
any methods that are specific to that type of media. 


Define a relationship to the existing class 


If someone has defined a class called EMailAddress to 
handle electronic mail addresses, you can take advantage of 
this simply by including a property of type EMailAddress in 
one of your own classes. 


Copy and modify the source code 


This is a last resort which does not give the full benefits of 
object-oriented reuse; you will save coding effort but will 
still incur validation costs, and you will not be able to take 
advantage of later enhancements to the code you are reusing. 
However, if what you want to do is sufficiently different 
from what the original class designer intended, it may be the 
best pragmatic option. Note that the source code of methods 
is often accessible using the operation getMethodSource(). 
The source code may be subject to copyright or licensing 
restrictions. 
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The following illustration shows the class hierarchy for a project 
management database: 


Application_Object 


The classes shown in this example are as follows: 


Application_Object 


This class provides common—mostly implementation— 
details shared by the other classes. It is worth having a 
single top-level class in a class family even if you do not 
know at first what it will be used for. It will often prove a 
useful place to put your own diagnostic or administrative 
methods. 


Project 
This class represents a project on which people are engaged. 
Location 


This class contains information regarding a site. This 
includes addressing information and pictures associated 
with the site. 


Person 


This class represents people of interest to the application. 
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=» Manager 


This class is a subclass of Person. It represents people who 
are either managing a project or who have line management 
responsibility for other people. 


Defining the Attibutes 


Attributes or Methods? 


Deciding what attributes you want to record for your classes is 
usually something that causes little difficulty, once the 
requirements analysis is finalized. This section discusses some of 
the design choices that can arise. 


You can publish the interface to a class primarily in terms of 
attributes that the user can retrieve or update, or you can publish 
it primarily in terms of methods that the user can invoke. For 
example, you could provide an attribute surname or a pair of 
methods, getSurname() and putSurname(). 


The advantage of publishing the interface in the form of methods 
is that you have much more flexibility in how to store the 
underlying data. For example, the surname might be stored as a 
separate attribute, or you might store a full name (for example, 
“Spencer, William James”) and extract the surname from this on 
demand. This kind of interface is particularly suitable if your 
methods are part of a product that will have a large number of 
users demanding compatibility from one release to the next. 


The disadvantage of doing everything through methods is 
performance. This is particularly true for a query. If surname is 
available as an indexed attribute, a query that mentions it 
explicitly will be much more efficient than one that accesses it 
through a method. 
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One compromise is to allow users to read attributes directly but 
only to update them via methods. You cannot enforce this, but 
you can make it standard coding practice. This allows you to 
write methods that perform validation of new values or that 
maintain redundant or derived information. (You could also, if 
you wanted, have your update methods maintain a checksum 
which would allow you to detect if attributes had been directly 
updated against the rules.) 


Overloading of Attributes 


Composite Attributes 


Overloading occurs where one attribute can be deduced from 
another—for example, where a person’s sex can be deduced 
from their personnel number, or where the manufacturer of a 
part can be deduced from the part number. This is often a 
serious problem in complex databases because the applications 
make assumptions about the data that can be invalidated by 
subsequent business changes. 


With Jasmine you can remove some of the problems caused by 
overloading by capturing the hidden semantics in methods. For 
example, you can define a method getSex() on Person to return 
the sex of the person. This method can then be the only thing 
that knows how sex is encoded in a personnel number; and if the 
algorithm changes, the method can be rewritten. 


Should a person’s address be recorded as a single attribute, or as 
a collection of attributes such as Street, City, State, and so on? Or 
perhaps it should be a collection-valued attribute, with one 
element for each line of the address? 


There is no definitive answer to this set of questions. It is 
probably best to split the data up as finely as you can, but this 
can depend on how far it is possible to capture existing 
information: can you actually extract the City and State from 
your current address data? Again you can use methods to mask 
the detailed attribute structure you have chosen. 
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Choice of Data Type 


The table below gives some guidance on the use of the atomic 
data types in Jasmine: 


Data Type Used For Avoid Using For 

Boolean Attributes that are either Other attributes that have two possible 
TRUE or FALSE values (for example, gender) 

ByteSequence Binary data whose internal Any situation where a more specific 


structure is unknown or which data type (for example, String) is 
does not conform to any of the available 


other data types 

Date08/18/98 Date value, including month, Any attribute other than a calendar 
day, year, and era date 

Decimal Numeric data requiring fixed Situations where Integer or Real would 
precision arithmetic (for be adequate 


example, currency amounts) 


Integer Whole numbers representing a Phone numbers, zip codes, and so on, 
numerical quantity where leading zeros are significant and 
arithmetic is meaningless 


Real Physical measurements (for Currency amounts 
example, height and weight) 


String Character data Binary data 


Attributes that have a small set of possible values (for example, a 
status value that is either Pending, Running, or Stopped) can be 
represented by either an Integer or a String value. Integer values 
are more convenient for processing, while String values might be 
more meaningful to end users. 
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Handling Abstract Data Types 


In some cases you may want to represent an attribute using an 
abstract data type where you do not want to make the internal 
representation visible. Examples of abstract data types that you 
often encounter are: 


Measures (for example, longitude and latitude) 


Multimedia data types (for example, image and sound) 


There are two ways of representing such values in Jasmine: 


Defining a class 


You can represent the abstract data type by a class of its own. 
This is what has been done in the Jasmine multimedia class 
family described in the Class Reference Supplement. The 
advantage of this approach is that the semantics are very 
clear in your class definition and that you can hide the 
detailed representation. The disadvantage is that you need 
to manage the creation and deletion of these objects: you do 
not want your database cluttered with objects that are no 
longer being used. 


Choosing a literal representation 


You can decide, for example, that values are to be 
represented by a string attribute in a particular form. If you 
do not want to publish the representation, you can provide 
methods that hide it. For simple attributes, this approach is 
probably more practical in most cases, though not quite as 
elegant as defining a class. 
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Use of Collection-Valued Attibutes 


Collection-valued attributes are useful where there are multiple 
values for an attribute (for example, the forenames of a Person). 


As already discussed in Normalization earlier in this chapter, it is 
best to avoid using collection-valued attributes for situations 
where the individual values are—or are likely to become— 
non-atomic, since such structures quickly become unmanageable. 


Defining the Relationships 


The factors that you need to consider when you are deciding 
how to handle relationships include: 


= The benefit of using object references rather than primary 
keys 


« Alternative ways of maintaining one-to-many and 
many-to-many relationships 


« Maintaining referential integrity 


Object References versus Primary Keys 


In a relational database, relationships between two objects 
(tables) are represented by including the primary key of one as a 
column in the other. The primary key is a user-maintained 
unique identifier, such as a part number or a personnel number. 
To retrieve the related data from two tables, you use a join query, 
which asks for data from the two tables with matching attribute 
values from the relevant columns. 


It is much more natural and efficient in Jasmine to represent 
relationships directly by references from one object to another. 
These references in practice consist of the internally allocated 
object identifier of the referenced object. 
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In a relational database, you would represent the relationship 
between a person and their boss by including “personnel 
number of boss” as a column in the person table. In Jasmine you 
would instead include the object identifier of the boss in a 
property called a relationship. 


Using the object reference is more efficient. This is partly 
because Jasmine can access objects very efficiently given their 
internal identifiers, and partly because the fact that you are 
following a relationship is evident in the way you write a query 
and does not have to be deduced by a complex optimizer. The 
one drawback is that it makes the operation of loading data into 
the database rather more complex. For this reason, there might 
be some situations where you want to continue representing 
relationships the relational way. 


One-Way or Two-Way Relationships 


In a relational database, a relationship like the one shown below 
is always stored in one direction only. Typically, ina 
one-to-many relationship like that between a location and the 
people working in that location, the person table contains a 
reference to the location table; there is no reference in the 
opposite direction. To find all the persons based at a given 
location, a query is issued on the Person table. 


Person p Location 


The same technique can be used in Jasmine. Instead of the 
Person object containing the primary key of the Location, it 
contains its object identifier; but otherwise the design is 
unchanged. A query on the Person class can still be used to find 
all the persons at a given location and, if the relevant property is 
indexed, this will execute very efficiently. This is the simplest 
way of representing a one-to-many relationship in Jasmine: use a 
single-valued property to represent the “many-to-one” direction 
of the relationship. In the project management example, this is a 
property of type Location in the Person object: 
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Another option is to maintain references in both directions: 
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A third option is to maintain references in the one-to-many 
direction only: 
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A fourth option is to use an index on the many-to-one reference: 


Index Person 
> : Location 
Location 


There is a potential advantage of maintaining the one-to-many 
relationship which, in the project management example, would 
be a property of type collection-of-Person in the Location object. 
This advantage is that access in the one-to-many direction is 
faster, although the difference is not great, compared with using 
an index on the many-to-one reference. 


As with attributes, it can be useful to hide the way you have 
chosen to represent a relationship by using methods. Again, this 
is perhaps more important for update than for retrieval. If you 
choose to maintain relationships in both directions, you can use 
update methods to keep the two in step. Retrieval methods are 
useful to hide whether you have implemented the relationship in 
the one-to-many direction or the many-to-one direction or both. 
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A useful collection of methods to provide, say, for the 
relationship from Person to Location, might be as follows: 


Class Retieval Methods Update Methods 
Person getLocation() putLocation(Location loc) 


Location getPersons() addPerson(Person p) 
removePerson(Person p) 


Many-to- Many Relationships 


Ina relational database, many-to-many relationships always 
require an extra table. For example, if one person can belong to 
several projects and one project can involve several persons, then 
there will be a linking table PersonOnProject with one entry for 
each (project, person) pair. 


Many-to-many relationships can be represented directly in 
Jasmine, using a collection-valued relationship property at either 
or both ends. 


Before choosing such a representation, however, make sure that 
there is no data associated with the relationship. For example, if 
you need to record the date when a particular person joined a 
particular project, it is best to introduce an extra linking class as 
in the relational implementation. 


This linking class will then have two one-to-many relationships 
with the original Project and Person classes. 


You can hide the existence of the linking class by providing 
methods to navigate the many-to-many relationship directly; the 
methods can be the same whether there is a linking object or not. 
In the project management example the methods might be as 
shown in the following table: 
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Class Retieval Methods Update Methods 


Person getProjects() addToProject(Project j) 
removeFromProject(Project j) 


Project getPersons() addPerson(Person p) 
removePerson(Person p) 


Referential Integrity 


The term referential integrity means that an object should never be 
allowed to refer to an object that does not exist. If an object is 
deleted, all references to it should be updated in some way. 


In Jasmine, referential integrity is optional. You can choose to 
allow your database to contain references to deleted objects. An 
error will be reported if you attempt to follow such a reference, 
and you can intercept this error and act accordingly. In some 
cases this might be the best way of modeling the real-world 
situation—for example, the author of a book might have died, 
but his name will still be present on the book. 


If you want to achieve referential integrity, you can do this by 
refining the system-supplied delete() method. For example, if 
you want to remove a person from a project if the person is 
deleted, you can refine the method delete() for Person so that, 
before doing the actual delete, it updates the relevant projects. 
The method might look like this: 


defineProcedure Void Person: :instance:delete() 
{ 

$Project j; 

$Bag<Project> jj; 

$33 = self.getProjects(); 

$scan( jj, j ) { 

$self .removeFromProject (3) ; 
hj 


$self.super: :delete() ; 
$return; 


}; 


Designing a Database 5-25 


Logical Database Design 


Defining the Methods 


The factors you need to consider when you are defining methods 
include: 


= Deciding whether a function should be defined as a method 
or as a procedure in the application 


= Deciding which class a method should be applied to 
= Using methods to access external systems 


# Polymorphism 


When to Use Methods 


It is generally best only to use Jasmine methods to implement 
that part of the application that is concerned with information 
management, and to avoid using them to implement parts of the 
business process or the presentation. 


The main types of user-defined methods are methods that: 


= Obtain information, which can be derived indirectly or 
obtained from outside the Jasmine database 


= Update information, which can be stored in a different or 
redundant form from that supplied, possibly outside the 
Jasmine database 


« Trigger side-effects (for example, the printing of a report) 


Defining the interface to a class in terms of methods can be very 
useful to mask details of the implementation, but it can also be 
inefficient, especially where queries are required. In practice it 
will often be necessary to publish some of the properties of the 
class as well. 
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Tip: Most things that can be done in the application program 
can be done equally in methods, and vice-versa. There are 
some exceptions—notably that transactions can only be 
started, ended, or rolled back from the application program, 
not from methods. This means it is best to keep the 
execution of methods reasonably short and certainly 
non-interactive. 


Deciding the Target Class fora Method 


In many cases it will be obvious what a method should be 
attached to, because there is only one object involved. A method 
to determine the spending limit of a person, for example, should 
obviously be an instance-level method on the class Person. 


Sometimes it is not so obvious. This may be because there are no 
objects involved, or because there are several. 


An example where no objects are directly involved is a method 
to determine how many days are available before the next 
monthly payroll. It is generally best to make such methods class 
methods—if necessary inventing a dummy class, such as 
PayrollSchedule, solely to attach the methods to. Such a class 
might have no instances. This is the approach adopted, for 
example, with the system class FamilyManager. 


An example where several objects are involved is a method to 
assign a person to a project. This can equally well be an 
instance-level method on Person or an instance-level method on 
Project. To some extent the decision is arbitrary: one object will 
be the target of the method, the other will be a parameter. It is 
even possible to provide both: Person.addToProject(Project j) and 
Project.addPerson(Person p). 


If the method is likely to be polymorphic with respect to one of 
the objects involved, then that object should be the target. For 
example, if the method is likely to be different for different kinds 
of projects, it should be an instance method on the Project class. 
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In a few cases you may want the operation to be doubly 
polymorphic. For example, the method for printing a document 
on a printer depends both on the class of document and on the 
class of printer. The usual way of handling this is to try to divide 
the operation into two phases, so that the first phase depends on 
the class of document and the second on the class of printer. 


Using Methods to Access Extemal Systems 


An object database can be very useful to encapsulate existing 
data stores, hiding the details of where information is actually 
held. 


Since methods can be written in C or C++, they can use whatever 
techniques are available to access the information. This might 
include: 


= System calls to access operating system files, electronic mail 
services, and so on 


= SQL requests to access a relational database, either locally or 
remotely 


= Calls on an object request broker to access distributed object 
services 


There are a few general points that apply to all such situations: 


« The method needs to allow for the fact that the data can be 
changed without Jasmine’s involvement 


Useful techniques to detect that such changes have 
happened include timestamps and checksums. The 
timestamp or checksum can be stored in the Jasmine 
database and compared with the external data next time it is 
read to see if it has changed. 
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= Ifthe method changes the external data, the changes will not 
be rolled back if the Jasmine transaction fails 


One way of circumventing this problem is always to create a 
new version of the external data (for example, a new file). If 
the file name of the current version is held in the Jasmine 
database, this file name will revert to its previous value 
when the transaction is rolled back, ensuring that subsequent 
accesses ignore the changed file in favor of the original one. 


Jasmine supports the use of polymorphism. This allows you to 
have a single operation that can be implemented in different 
ways according to the class of object to which it is applied, rather 
than having conditional code in the application program for each 
different class. For example, the method spendingLimit() 
calculates an individual’s spending limit. When applied to the 
class Person, the method returns a constant value such as 125.50. 
When applied to the class Manager, it returns the sum of the 
spending limits of the appropriate manager’s subordinates. 


To implement this method, you would define it once for the class 
Person and then redefine it for the class Manager, which is a 
subclass of Person. The only request made to the application 
program is for execution of the method in the superclass. The 
system automatically determines which version of the method 
suits each object, and then selects and activates this version in the 
appropriate class. 


Using polymorphism gives you the flexibility to add new 
information to the database without changing the application 
program, even when there is an increasing number of subclasses 
in the class hierarchy and the relationship between the 
superclasses and subclasses becomes complex. 


Try to use polymorphism to eliminate coding that takes account 
of special cases in your application, for example, to get rid of 
complex nested conditionals that make maintenance difficult. 
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If your application is handling employees’ expenses and you 
need to treat temporary employees from overseas subsidiaries as 
a special case, do not add conditional code to the application 
program to do it. Instead, introduce a subtype of Employee and 
put the special case code there. Not only does this make the 
application program far easier to maintain, it allows special cases 
to be introduced at any time without changing the code for the 
general case. 


Physical Database Design 


The physical database design stage consists of the following two 
steps: 


1. Define the stores. 


2. Define the indexes. 


Defining the Stores 


Although creating the stores is the first thing you do when you 
actually start implementing a database, stores are not the first 
thing to think about in the design process. This is because stores 
belong to the physical level of the design and you, therefore, 
need to consider them after you have produced your logical 
design. 


Even when you do reach the physical design stage, it may not be 
appropriate for you to produce a final design for the stores 
immediately. Typically, you will have a single user store during 
early prototyping and then think about having multiple stores 
later on. 


When you create a store, you can specify more than one file for 
it, which is valuable if you want the storage for the store to span 
multiple drives. As a result, it is not usually necessary to split a 
database into multiple stores purely in order to manage use of 
disk space or to spread the input/output load. You can also 
expand the size initially allocated to a store using the command 
extendStore if the store outgrows the initial disk space estimates. 
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Defining the Indexes 


As data volumes increase, maintaining the right indexes can 
make a dramatic difference to performance. As with a relational 
database, a query that attempts to match a given property value 
will use the index, if there is one, for direct retrieval, but will 
scan all the instances of the class if there is none. 


In some ways indexes are less important than in a relational 
database because many objects will be accessed navigationally by 
following relationships, rather than by queries. Note, however, 
that it can be very useful to exploit indexes to follow a 
relationship in the inverse direction. 


Indexes can be defined at any time using the createIndex() 
operation, and they can be deleted at any time using 
dropIndex(). To find out what indexes currently exist for a class, 
use printIndex(). To display index information for a class, all 
classes in a family, or all classes in a store, use the listIndex() 
system command. ListIndex() can also be used to compact an 
index that has become fragmented. 


Tip: Avoid using indexes if the frequency of update is high 
compared to the frequency of query for the property in 
question. Otherwise, you will incur all the costs of 
maintaining the index without getting a corresponding 
benefit. In particular, avoid having indexes present during 
bulk database loading operations; it is better to create the 
index once the data has been loaded. 


Although indexes are intended primarily to allow Jasmine itself 
to optimize queries, you can also exploit indexes directly from 
your code using the indexScan statement in ODQL. This allows 
you to retrieve instances with a range of values, in order of the 
indexed value. Because such code takes advantage of knowledge 
of indexes, it achieves a performance advantage at the expense of 
potential for change. So it is a trade-off you should consider 
carefully. 
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In This Chapter 


This chapter provides general information on how to use ODQL. 
The more specific information about using ODQL which appears 
in subsequent chapters of this guide assumes that you have 
already read and are familiar with the information in this 
chapter. 


Where You Use ODQL 


You can use ODQL in a number of contexts. 
s Interpreted ODQL can be: 


- Used directly from the terminal using the codqlie 
command 


- Executed from a file by piping input into the codqlie 
command, specifying the -execFile command line option, 
or using the execFile command 


=» Embedded ODQL (in C or C++) is used to write the code of 
methods. 


=» ODQL statements and commands can be executed from the 
C API using the odbExecODQL() function, while methods 
can be executed using the odbExecMethod() function. 
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The defaultC F Declaration 


Refer to the “Using Interpreted ODQL” and “Using Embedded 
ODQL” chapters of this guide for more information about these 
subjects. For information about using the C API, refer to the 

C API Programmer’s Reference guide. 


The defaultC F Declaration 


As discussed in Class Families in the “Object Database Concepts” 
chapter, class names in Jasmine need only be unique within a 
class family. Therefore, to identify a class uniquely, it must be 
qualified by the name of the class family. For example: 


demoCF: :Person 


To improve readability of ODQL programs, a defaultCF 
declaration can appear anywhere an ODQL statement can 
appear. This specifies a class family name that will be used by 
default where unqualified class names are used. For example: 


defaultCF demoCF; 


The defaultCF declaration is not an executable statement. It 
affects all unqualified class names appearing textually later in the 
input stream. If written in a block, it remains effective after the 
end of that block, and it is effective even if the block is never 
executed. 


Classes in the system class family systemCF (for example, 
Integer) never need to be qualified unless there is a class of the 
same name in a user class family. 
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Example 1 


Example 2 


Example 3 


Example 4 


Example 5 


An ODQL variable is a reference to one of the following: 


An entity A collection of entities 

An atomic literal A collection of atomic literals 
A class A collection of classes 

A tuple A collection of tuples 


In each case you must give the variable a type. The type of the 
variable determines what values it can take. Some examples are 
given below: 


$Person p; 


The value of p is an instance of the class Person or of a class 
subordinate to Person. 


$Bag<Person> pp; 


The value of pp is a bag; every element of the collection must be 
either an instance of the class Person or an instance of a class 
subordinate to Person or the special value NIL. 


$String s; 
The value of s is a String. 


$Bag<String> ss; 


The value of ss is a bag of Strings. Each of the elements must be 
either a String or NIL. 


$Person class PC; 


The value of PC is a class; this must be either the class Person 
itself, or a class subordinate to Person. Note that the class, which 
is Person in this example, must be a user-defined class or 
Composite. 
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Example 6 


Example 7 


Example 8 


Example 9 


$Bag<Person class> PCS; 


The value of PCS is a collection of classes; each of these classes 
must be either the class Person itself, or a class subordinate to 
Person, or NIL. Note that the class, which is Person in this 
example, must be a user-defined class or Composite. 


$TS [Integer hours, Integer minutes, Real seconds] 
timestamp; 


The value of timestamp is a tuple containing three components: an 
integer called hours, an integer called minutes, and a real number 
called seconds. The name TS is optional; it is a name for the tuple 
class. Two tuple variables using the same tuple class name must 
have components that match in name and class. Such variables 
are said to be compatible tuples. Tuples can only be assigned to 
each other or compared with each other if they are compatible. 


$Bag<TS [Integer hours, Integer minutes, 
Real seconds]> timestamps; 


The value of timestamps is a collection of tuples each containing 
three components: an integer called hours, an integer called 
minutes, and a real number called seconds. 


$Person p, q, class PC, r; 


Several variables can be combined into a single declaration. The 
qualifier class applies only to the variable that immediately 
follows. So the above example is equivalent to: 

$Person p; 

$Person q; 


$Person class PC; 
$Person r; 
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Scope of Variables 


Declarations are block-structured as in C or C++. Variables 
declared within a block cease to exist at the end of the block. 


When you declare a variable at the ODQL interpreter prompt— 
that is, not within a block—the variable normally remains in 
existence until the end of the session, and retains its value until it 
is updated. 


There are three techniques that you can use to get rid of variables 
and their values before the end of the session: 


=» You can use the undefVar command to cancel the declaration 
of specific variables or of all variables for the session. This 
allows the variable names to be re-used. For example: 


Bag<Person> pp; 
Ppp = Person from Person; 


undefVar Pp; 

Bag<Project> pp; 

pp = Project from Project; 

The undefVar command is available in interpreted ODQL 
and dynamic ODQL, but not in embedded ODQL. 


=» You can use the delete() collection method to release the 
space occupied by a collection (for example, the result of a 
query) in the work store. The variable remains declared but 
its value can no longer be referenced. For example: 


Bag<Person> pp; 
Ppp = Person from Person; 


pp.delete() ; 


=» You can use the Session.clear() method to release the space 
occupied by all collections in the work store. Again, existing 
variables remain declared but their values become 
inaccessible. 


Generally, variables are not affected by transaction boundaries: 
rolling back a transaction will not cancel the declaration of a 
variable or reset its value. The exception is for collection-valued 
variables, where an implicit delete() is carried out when a 
transaction is rolled back to delete the values (but not the 
declarations) of collections established during that transaction. 
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Note that at session level—at the ODQL interpreter prompt— 
variables can be declared at any time. Within a block, however, 
variable declarations must precede the first executable statement 
in the block. 


Entities and Literals 


Entities 


Literals 


As explained in Classes in the “Object Database Concepts” 
chapter, there are two kinds of objects in Jasmine: entities and 
literals. 


Entities exist in the database and have object identifiers. You 
create entities in the database using the new() method, and delete 
them using the delete() method. User-defined classes, such as 
Person and Manager, are subordinate to the system-defined class 
Entity, so all instances of these classes are ultimately instances of 
the class Entity. 


Tip: When you declare an ODQL variable whose value is an 
entity—for example, Person—you may find it helpful to 
think of the value of the variable being a reference to the 
object in the database, or more tangibly you can think of the 
value as being the object identifier. 


Literals are simple values, such as numbers and character strings. 
Jasmine supports two kinds of literals: 


» Atomic literals, which belong to one of the following types: 
- Integer 
- Date 
-— Decimal 


— Real 
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- Boolean 
— String 
—  ByteSequence 


For Decimal values, a precision and scale must always be 
given. The precision is the total number of decimal digits (1 
to 18); the scale is the number of these digits that occur after 
the decimal point. For example, Decimal [ 10, 2 ] describes a 
number with eight digits before the decimal point and two 
after. 


For Strings and ByteSequences, a maximum length can be 
given in the range 1 to 65,536. In the case of String, the 
length includes the terminating NULL (\0) byte added by 
the system. For example, an attribute that is to contain the 
value “M” or “F” can be described as String [2]. If no 
maximum length is given, the limit is 65,536. All strings and 
byte sequences are stored internally in a variable length 
format. 


For detailed descriptions of these types, see the relevant 
entries in the Reference guide. 


Tuples 


Tuples are composite values containing a number of 
components. These components can be atomic literals or 
entities, collections of literals, collections of entities, 
user-defined classes, or collections of user-defined classes 
(but not tuples). Tuples are used for one purpose only, to 
define a data structure into which database information can 
be selectively retrieved. They are described in detail in the 
Reference guide. 
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Constants 


You can write literal values in ODQL in the form of constants. 
Here are some examples: 


Type Examples 

Decimal 23.4, -18, +0.002, .5 

Real 1.0e-6, -3.512e+10, +1000e-03 
Boolean TRUE, FALSE 

String “Smith,” “O’Connor,” “Hello!\n” 
ByteSequence X“0001 ffff0002fffe” 


Note: Dates08/18/98 have no direct constant representation. 
Instead, you can use the construct() method or represent the Date 
as a string or number and convert it using the convertToDate() 
method. 


You can also write a collection of literals as a constant. For 
example: 


List{ 2, 3,5, 7, 11,13} 
Set{“Smith”, “O’Connor”} 


A collection that has no elements is said to be empty and is 
represented by excluding the elements in between the braces. 
For example: 


List<Person> pp; 
pp = List{}; 


Jasmine treats constants such as “17” or “-359” as Decimal 
constants rather than Integer constants. If the constants are used 
in a context where an Integer is required, however, the 
appropriate conversion occurs automatically. 


Detailed rules for writing constants are given in the Reference 
guide. 
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The NIL Special Value 


NIL is used to indicate the absence of a value. It can arise ina 
number of circumstances: 


« All variables are initialized to NIL when they are first 
declared 


« The properties of newly created objects in the database are 
set to NIL unless some other value has been assigned 
explicitly or as a default value 


» NILis returned by certain methods 


For example, the getMethodSource() method returns NIL if 
the method has not been defined. Many methods return NIL 
if one of the inputs is NIL. 


« A variable can always be set to NIL explicitly by assignment 


For example: 


$x = NIL; 


NIL is not the same as any other value. In particular, it is not the 
same as the number zero, or a zero-length string, or a collection 
with no elements. NIL means unknown or not applicable. 


In a query, an object is not selected if the predicate evaluates to 
NIL. 


Note: In expressions and queries, NIL in Jasmine behaves in a 
very similar way to NULL values in SQL. There is one important 
exception, however: unlike SQL, NIL is equal to NIL. So in 
ODAQL, the predicate if (x == NIL ) can be used to test whether a 
value is NIL or not. 
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Assignment 


You can assign values to ODQL variables as in any other 
programming language. For example: 


Integer n, m; 
Bag<Integer> nn; 


String s; 

n= 17; 

m = NIL; 

nn = Bag{ 12, 14, 17 }; 
s = "Canada"; 


The type of the value or expression on the right must be 
compatible with the type of the variable on the left. For example, 
you can assign: 


» Asstring to a variable of type String 
«» A collection of Persons to a variable of type Bag<Person> 


=» Asubclass of Person to a variable of type Person class 


The type of the value can be a subordinate class to the type of the 
variable. This is shown by the following example of a request 
(for additional information about requests, see Requests later in 
this chapter). Here a Person variable can take a Manager as its 
value: 

Manager m; 

Person p; 

m Project .find("Jasmine") .manager; 

Pp m,; 


The opposite is not true. The type of the variable on the left 
cannot be a subordinate class to the value on the right. Where it 
is necessary to achieve this, it can be done with a cast, shown in 
the last line of the example below: 

Manager m; 

Person p; 


p = Project.find("Hong Kong Airport") .manager; 
(Manager) p; 


3 
Wo 


This only works when the current value of p is a Manager. If the 
value of p were a person who was not a manager, the cast would 
fail. A cast cannot be used to bypass Jasmine’s type-checking; 
what it does is defer type-checking until execution time. 
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Single values must be assigned to single variables, 
collection-values to collection-variables, and class-values to 
class-variables. However, a collection-value can be assigned to a 
single variable if the collection has only one element: 

Integer n; 

Bag<Integer> nn; 


nn = Bag{5}; 
n = nn; 


The reverse is not possible. You cannot use a collection-variable 
on the left-hand side and a single value on the right. To achieve 
this effect you need to use the add() method: 

List<Integer> nn; 


nn = List{}; 
nn = nn.add(5); 


There are three kinds of expressions in ODQL: a query, a 
grouping expression, and a formula. Queries and grouping 
expressions are used to select and group elements of a collection, 
and are discussed in Database Access later in this chapter. 


In general, a formula consists of terms—which can be constants, 
variables, or requests—connected by operators. Requests are 
used to access the properties or methods of objects in the 
database, and are discussed in Requests later in this chapter. 
You can write a formula in ODQL as in most conventional 
programming languages. 


The following arithmetic operators are available: 


Arithmetic Operator Applies To 

+ Add Numeric literals * 
- Subtract Numeric literals * 
* Multiply Numeric literals 
/ Divide Numeric literals 
% Remainder Numeric literals 
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* — This can be a monadic (for example, - 2) or dyadic (for 
example, 7 + 2) operator. 


The following comparison operators are available: 


Comparison Operator Applies To 


== EqualsError! Numeric, date, or string literals, 
Bookmark not classes, entities, tuples (but not 
defined. collections, or tuples containing 


collections) * 


{= Not equals Numeric, date, or string literals, 
classes, entities, tuples (but not 
collections, or tuples containing 
collections) * 


> Greater than Numeric, date, or string literals 
>= Greater or equal Numeric, date, or string literals 
< Less than Numeric, date, or string literals 
<= Less or equal Numeric, date, or string literals 


* The tuples must be compatible; that is, they must have the 
same class name and the same components. 


The following Boolean operators are available: 


Boolean Operator Applies To 

and Both operands TRUE Boolean literals 
or At least one operand TRUE ___ Boolean literals 
not Operand FALSE Boolean literals 


The normal rules of precedence apply and can be overridden by 
parentheses. 
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Generally, if one of the operands is NIL, the result is NIL. The 
exceptions to this are: 


Operator Result 


== NIL is equal to NIL and is not equal to any other 
value. 


I= NIL is equal to NIL and is not equal to any other 
value. 


and Returns FALSE if one of the operands is FALSE, 
even when the other operand is NIL. 


or Returns TRUE if one of the operands is TRUE, even 
when the other operand is NIL. 


Where to Use Expressions 


Expressions can be used in a number of contexts: 


= Any expression can be used on the right-hand side of an 
assignment 


= A Boolean expression can be used in the where clause of a 
query, or in an if-statement or while-statement 


« A formula can be used in the target-specification of a query 
to define values returned by the query 


« A formula can be used ina return-statement to indicate the 
value returned by a method 


However, there are other contexts where a general expression 
cannot be used including, for example, parameters to method 
invocations. Check the language syntax in the Reference guide. 
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Here is an example of a fairly complex formula used on the 
right-hand-side of an assignment: 


Boolean b; 
Integer n; 
Person p; 
Person class m; 


b = (n > 5 and p.spendingLimit() < 100.00) 
or (p.getInsToClass() == m); 


Methods in Expressions 


Many general purpose operations on literal values are provided 
not by ODQL operators, but by methods. Full details of these 
methods are provided in the Reference guide. They include: 


=» Methods for converting values of one kind to another, such 
as convertToString() 


= Methods to concatenate Strings and ByteSequences, such as 
stringCat() and byteSequenceCat() 


« Methods to combine or manipulate collections, such as 
union(), intersect(), and differ() 


« The like() method (described in the topic Pattern Matching in 
Strings), used to perform pattern matching in strings 


6-14 Using Jasmine 


Flow of Control 


Pattem Matching in Strings 


The method like() allows you to perform pattern matching on 
strings: 


..where Person.name.like("Smith*") ; 


You can use the special characters “?” to match any single 
character and “*” to match any sequence of zero or more 
characters. 

If you want to use the characters “*” or “?” as part of the pattern, 
precede them with a user-selected escape character. For 
example, the following matches any string ending in a question 
mark: 


where Employee .notes.like("*&?", 
escapeCharacter :="&") ; 


How of Control 


if Statement 


ODQL provides constructs similar to those in C to perform 
iteration and conditional execution. These constructs include an 
if statement, a while statement, and a scan statement. The syntax 
of these statements is given in the Reference guide. Here are some 
examples. 


The if statement is used for conditional execution: 


if (n<0O) { 
msg = "Value of n is negative\n"; 
msg.print (); 


else { 
p=n*n,; 


}; 
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while Statement 


scan Statement 


Note that the condition must be surrounded by parentheses, as 
in C. Unlike C, the two possible actions to be taken must be 
written as blocks, even when there is only a single statement. 
The else part can be omitted. 


If the condition is NIL, execution proceeds as if it were FALSE. 


The while statement is used for iteration based on a terminating 
condition: 
while (n< 5) { 
msg = String.format ("Value is %s\n", n); 
msg.print (); 
n=n+dl; 


}; 


The body of the while statement must be a block, even if it only 
contains a single statement. The condition is tested before entry 
to the block, and the block is executed if it is TRUE; iteration 
ends when the condition is FALSE or NIL. The loop can also be 
terminated by executing a break statement. 


The scan statement is used to iterate over all elements of a 
collection: 


Bag<Integer> nn; 
Integer n, m; 
nn = Bag{ 2, 3, 5, 7 }; 
scan (nn, n) { 
m= 2 * n; 
m.print () ; 


}; 
> 4 
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The scan statement names two variables, a collection-valued 
variable that identifies the collection to be iterated over, and a 
single variable of the same type that will be used to refer to each 
element of that collection in turn. Both of these variables must 
already have been declared. The body of the scan statement 
must be a block, and is executed once for every element of the 
collection. On exit, the single variable will be NIL. 


You might find it helpful to read: 


scan ( pp, p) {... } 


as: 
For each p in pp do{... } 


You can end the scan prematurely by executing a break 
statement. In this case the single variable retains its value at the 
time the break statement was executed. 


Another way to iterate over a collection is to create an iterator 
using the createlterator() method. This allows more flexibility 
than the scan statement—for example, you can process a 
collection from bottom to top and can have multiple iterators 
active on a collection at the same time. For more information, 
refer to the Iterator class entry in the Reference guide and to the 
section entitled Using an Iterator later in this chapter. 


Database Access 


The primary role of ODQL is as a database access language. 
There are two ways of finding objects: 


= By query (looking for objects that match given criteria) 
=» By navigation (following relationships between objects) 


Having found an object of interest, you can retrieve its properties 
and invoke its methods. 
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Queries 


This section describes the ODQL constructs used to access data, 
in particular: 


= Queries, used to select objects based on the values of their 
properties 


= Requests, used to follow relationships, access attributes, and 
invoke methods 


=» Grouping expressions, used to partition collections according 
to the values of properties 


= The indexScan statement, used to access objects efficiently by 
directly exploiting an index 

The section also covers the following related topics: 

» Navigation 

=» Operating on collections 

» The empty collection 

= Creating new objects 

« Updating properties of objects 

= Deleting objects 


=« Use of metadata 


A query is an ODQL construct that retrieves data satisfying 
given conditions. The result is a collection of objects. The query 
is usually written on the right-hand side of an assignment 
statement, so that the result of the query is assigned to some 
variable. For example: 


List<Person> pp; 
pp = Person from Person where Person.grade == "10"; 


This query finds all people whose grade is “10.” The value of the 
variable pp will now be this collection of people. 
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The target of a query is, in general, a collection and is defined by 
the from clause of the query. The target collection can be: 


« Allinstances of a class, defined by using the class name 


In the example above, the input comprises all instances of the 
class Person including all instances of its subordinate classes. 
To exclude the subordinate classes, you could write: 
List<Person> pp; 


pp = Person from Person alone 
where Person.grade == "10"; 


« Allinstances of a class, defined with a range variable 


This would allow the above query to be expressed as: 


List<Person> pp; 
Ppp = p from Person p where p.grade == "10"; 

« All elements of a collection, defined using a variable whose 
value is the collection: 


List<Person> pp2; 
pp2 = pp from pp where pp.nationality == "US"; 


It is also possible to specify several collections or classes in the 
from clause. The target of the query is then the Cartesian 
product of the collections, that is, the collection of all possible 
pairs of values taking one value from each of the collections. 


The example below illustrates this; it retrieves all of the people 
whose location is the same as the location of some manager but 
who is not necessarily their own manager. The third line of the 
example removes duplicate values from the result: 
List<Person> pp; 

pp = Person from Person, Manager 


where Person.location == Manager.location; 
Pp = pp.unique(); 


Tip: While retrieving a join in this way is common practice 
in a relational system, it is rarely necessary in Jasmine. 
Related objects can usually be found more conveniently by 
navigation, as described in the topic Navigation later in this 
chapter. 
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The result of a query can either be the objects themselves, or the 
result of applying a request to each object. Requests are 
discussed in the following subsection. A typical request is to 
return one of the attributes of the object. The following example 
returns the surnames of the selected persons as a collection of 
strings: 

Bag<String> ss; 


ss = Person.surname from Person 
where Person.grade == 10; 


It is possible to return several attributes: 


Bag<[ String surname, Bag<String> firstnames ]> 


people; 
people = [ Person.surname, Person.firstnames ] 
from Person where Person.grade == "10"; 


Here the result is returned as a collection of tuples. Each tuple 
has two components: a string representing the surname, and a 
collection of strings representing the first names. 


It is also possible to return derived data and constants in the 
result. For example: 


Bag<[ String surname, Decimal [8, 2] income, 
Boolean check ]> dd; 


dd = [ Person.surname, 
Person.salary + Person.bonus(), TRUE] 
from Person where Person.grade == "10"; 


Returning a constant might be useful if the result of this query is 
later to be combined with the result of another query. 


Using Range Variables 


A query can be written using range variables. For example, the 

following query uses the range variable p to refer to the class 

Person, which is the input to the query: 

Bag<[ String surname, Bag<String> firstnames ]> 
people; 


people = [ p.surname, p.firstnames ] from Person p 
where p.grade = "10"; 


The range variable is automatically declared by including it in 
the query. 
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Requests 


Property Requests 


Invoking a Method 


Database Access 


A query can be exclusive. If a class name is preceded by the 
keyword alone in the from-specification of a query, the query 
applies to the immediate instances of that class only and excludes 
instances of subordinate classes. 


Having found an object of interest in the database, it is possible 
to get information about it by means of a request. There are two 
kinds of requests: a property request and a method invocation. 


A property request returns the value of a particular property of 
an object. In the following example, the properties surname, 
height, firstnames, and location are requested and assigned to 
variables. 


Person p; 

| ae aE 

String s; 

Real r; 
Bag<String> ss; 
Location loc; 

s = p.surname; 

r = p.height; 

ss = p.firstnames; 
loc = p.location; 


To request an instance-level property, use a variable referring to 
the instance before the period (full-stop). To request a class-level 
property, use either the name of the class or a variable whose 
value is the class. 


A method request causes a method to be executed. For example: 


Person p; 


P= ...; 
Decimal [8,2] d; 
d = p.spendingLimit () ; 
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Nesting Requests 


To invoke an instance-level method, use a variable referring to 
the instance. To invoke a collection-level method, use a variable 
referring to the collection. To invoke a class-level method, use 
either a variable referring to the class or the class name itself. 


Requests can also be nested. For example: 
Decimal [8,2] d; 
d = p.boss.spendingLimit () ; 


This retrieves the spending limit of the boss of person p. 


You can also use requests inside a query: 


Bag<String> ss; 
ss = Person.surname from Person 
where Person.boss.location.name == "Dublin", 


This retrieves the surnames of every person whose boss is based 
in Dublin. 


Grouping Hements According t0. Common Property Values 


You can group the elements of a collection according to common 
property values by using a grouping expression. The grouping 
expression takes a collection of objects as input and groups them 
into a number of partitions, according to the defined criteria. 
The output is a collection of tuples. Each tuple contains 
information about one partition. The information returned for 
each partition can include the grouping values used to define the 
partition, the collection of elements that constitute the partition, 
or information derived from this, such as a count or average. 
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The following example counts the number of persons of each 
grade, and prints the result in ascending order of grade: 
Bag<T [ Integer grade, Integer num ]> gradeGroups; 
T [ Integer grade, Integer num ] g; 
gradeGroups = group Person by (Person.grade) 
with (partition.count) ; 
gradeGroups = gradeGroups.sort ("grade") ; 
scan ( gradeGroups, g ) { 
String out; 
out = String. format ("grade %d: %d", g.grade, 
g.num) ; 


}; 


The grouping expression consists of three elements: the grouping 
input, the grouping values, and the grouping result. 


You can identify the grouping input either by a class name or by 
the name of a collection-valued variable. If you specify a class 
name and the class has subordinate classes, these are included 
unless you qualify the class name with the keyword alone. 


The grouping values identify the criteria that the elements have 
to satisfy in order to be grouped together. If you want to 
compare the elements of the input collection to determine 
whether they should go in the same partition, the grouping 
values must include a by construct defining the criteria to be 
used for the comparison. 


The grouping result specifies what information is required about 
each partition. Any grouping values you defined in a by 
construct are automatically included. You can also return 
additional information in the result by using a with construct. 
The information you can return includes: 


« The partition itself, as a collection 


To return the collection of persons of each location: 


-.. = group Person by (Person.location) 
with partition; 
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« The result of applying a collection-level method to the 
partition 
To return the number of persons at each location: 


: = group Person by (Person.location) 
“with partition.count (); 


« The result of requesting a given property for each element in 
the partition 


To return the collection of grades of the persons at each 
location: 


: = group Person by (Person.location) 
“with partition. grade; 


« The result of applying a collection-level method to the 
collection of values of a given property of the elements of the 
partition 


To return the average grade of the persons at each location: 


-.. = group Person by (Person.location) 
“with partition.grade.average() ; 


For further information refer to the Reference guide. 


indexScan Statement 


The indexScan statement allows you to scan the instances of a 
class in ascending order of a given property, provided that this 
property has an index. You can also define the range to be 
scanned according to the values of this property. This allows 
efficient exploitation of indexes. 


The following example processes all Persons in ascending order 
of surname: 


Person.createIndex ( "SurnameIndex", "surname" ); 
indexScan (Person, p, "surnameIndex") { 
p.name() .print(); 


}; 
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You can also define the range to be scanned according to the 
values of the indexed property. The following example scans 
persons in order of surname, starting with those beginning with 
the letter M: 
indexScan (Person, p, "surnameIndex", 
ODB_EQGREATER, "M") { 
p.name() .print(); 


}; 


> Patrick John Murphy 
Edward Patton 
Joan Stephens 
Mary Ann Taylor 


The comparison can be any of the following: 
ODB_GREATER: greater than 
ODB_EQGREATER: greater than or equal to 
ODB_EQUAL: equal to 


If you want to process, say, all the persons whose surnames 
begin with the letter M, you can write this as follows: 
indexScan (Person, p, "surnameIndex", 
ODB_EQGREATER, "M" ) 
if (p.surname.like("M*")) { 
p.name() .print(); 
} 
else { 
break; 
} 
}; 


The break statement causes immediate exit from the innermost 
while, scan, or indexScan loop. 


Since an index applies only to the immediate instances of a class, 
the indexScan statement is always exclusive; that is, it includes 
only the immediate instances of Person and not any instances of 
classes subordinate to Person. 
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Navigation 


The properties of an object can contain references to other 
objects. The Invoking a Method section earlier in this chapter 
includes typical examples, which follow a reference from a 
person to their boss within a query. This is often the best way of 
following relationships in Jasmine and is much more efficient 
than performing relational joins. 


Often a relationship will be one-to-many and, in this case, you 
may want to process all the related objects in turn. This can be 
achieved using the scan statement or an iterator. For example: 
Person p; 

Bag<Person> pp; 

pp = Project.find("South Pole Expedition") .staff; 
scan ( pp, p ) { p.name.print(); }; 


Line three uses the user-defined class-level method find() to 
return the project called “South Pole Expedition.” It then 
requests the value of the relationship staff, which is the collection 
of persons assigned to this project, putting the result in variable 
pp. Line four scans the collection pp. The variable p is assigned 
to each element of the collection pp in turn, and the block 
between {} is then executed. The result is to print the full name 
of every person in the selected project. 


Operating on Collections 


It is often useful to manipulate collections as a whole, rather than 
always scanning them and processing them one object at a time. 
There are many Jasmine collection-level operations that make 
this easy. 
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Adding and Removing Hements 


With the exception of arrays, it is possible to add individual 
elements to a collection, and to remove individual elements: 


Bag<Person> pp; 

Person p; 

Project j; 

j = Project.find("Relief Aid"); 
pp = j.staff; 

p = Person. find("George Brown") ; 


Pp = pp.add(p); 
Pp = Person.find("Paul White") ; 


PP = pp.remove (p) ; 
j.staff = pp; 


Where very large collections are involved this can be inefficient, 
because the entire collection is retrieved into the variable pp just 
so that one element can be added or removed. If this is done 
repeatedly, it can also cause the work store to become full. In 
such cases a more efficient technique is to use the directAdd() 
and directRemove() methods, as follows: 

Project j; 

Person p; 

j = Project.find("Relief Aid"); 

Pp = Person.find("George Brown") ; 

j.directAdd ("projectMembers", p); 


p = Person.find("Paul White") ; 
j.directRemove ("projectMembers", p); 


A group of list-handling methods permit access to an element by 
specifying its location ina list, as either first or last or at a 
particular position. These methods can provide faster access 
than those that operate on the current element. For example, you 
can specify the position of the element you want to remove: 
List<Integer> ils; 

ils = List(2, 4, 6, 8, 10); 


ils .removeElementAt (2) ; 
ils.print (); 


> List{2, 4, 8, 10} 
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Combining Collections 


You can combine certain kinds of collections, such as sets and 
bags, by using operations like union, intersection, and difference. 
For example: 


Bag<Integer> nn, mm; 

nn = Bag{ 1, 2, 3, 4, 5 }; 
mm = Bag{ 4, 5, 6, 7, 8 }; 
nn.intersect (mm) .print () ; 


> Bag{ 4, 5 } 
nn.union (mm) .print (); 

> Bag{ 1, 2, 3, 4, 5, 6, 7, 8 } 
nn.differ (mm) .print () ; 


> Bag{ 1, 2, 3 } 


For example, you can use this technique to find people who work 
for both of two projects: 


Bag<Person> ppl, pp2, pp3; 


ppl = Project.find("South Pole Expedition") .staff; 
pp2 = Project.find("Relief Aid ") .staff; 
pp3 = ppl.intersect (pp2) ; 


Counting the Number of BHements 


It is possible to count the number of elements in a collection: 
Integer projectSize; 


projectSize = Project.find("South Pole 
Expedition") .staff.count (); 


Finding the Total, Average, Maximum, or Minimum 


With a numeric collection you can find the total, average, 
minimum, or maximum: 


Decimal [ 8,2 ] dl, d2, d3, d4; 
Bag<Decimal [ 8,2 ]> dd; 


dd = Person.spendingLimit () from Person; 
dl = dd.sum(); 

d2 = dd.average(); 

a3 = dd.min(); 

da4 = dd.max(); 
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Collections can be sorted. For example: 


Bag<String> ss; 
ss = Bag{ "John", "Mary", "Anne", "Zoe" }; 
ss.sort () .print (); 


> Bag{ Anne, John, Mary, Zoe } 


The sort() method sorts the elements of a collection into 
ascending or descending order. If you do not specify either of 
these, the default ascending order is used. The following 
example constructs a collection of persons with a spending limit 
greater than 1000. The elements are sorted by surname in 
ascending order: 

Bag<Person> pp; 

pp = Person from Person where 


Person.spendingLimit() > 1000.00; 
Pp = pp.sort ("surname") ; 


Note that a collection of entities can only be sorted on an 
attribute of the entities, that is, a property whose type is a literal. 
This a single-valued attribute. See the Reference guide for details. 


Collections can also be sorted by using the multiSort() method. 
This is similar to sort() except that you can specify multiple sort 
keys. Each key can be independently ascending or descending. 
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The following example sorts persons in descending order of 
grade and ascending order of surname within each grade: 


List<Person> pp; 
Person p; 
pp = Person from Person; 


Pp = pp.multiSort ("grade", DESCEND, 
"surname", ASCEND) ; 


scan(pp, p) { 
p-print () ; 
‘Me 


> demoCF: :Person::11{ 

surname = "King" 
grade = 25 

; ree 

demoCF: :Person: :10{ 
surname = "Bender" 
grade = 19 

; oes 

demoCF: :Person: :12{ 
surname = "Watson" 
grade = 19, 

; often 

demoCF: :Person: :6{ 
surname = "Carter" 


grade = 16 


You can use multiSort() in any context where you can use sort(), 
except to sort a collection of atomic literals. 
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Eliminating Duplicate Hements 


Using an Iterator 


Some collections, such as bags, can contain duplicate elements. 
Duplicates can be eliminated using unique(): 

Bag<Integer> nn; 

nn = Bag{ 1, 2, 3, 4 }; 

nn = nn.add(3); 

nn.print (); 


> Bag{ 1, 2, 3, 4, 3 } 
nn.unique() .print (); 


> Bag{ 4, 3, 1, 2 } 


If you need to process the elements of a collection one at a time, 
you can use an iterator instead of the scan statement. You do this 
by creating an iterator using the createlterator() operation, and 
then using methods defined on the Iterator class, such as 
advance() and get(), to process the iterator. 


In the following example, an iterator is used to print a collection 
of Integers: 


Bag<Integer> xs; 

Iterator<Integer> ii; 

Transaction.start (); 

xs = Bag{1,2,3}; 

ii = xs.createIterator(); 

while (ii.advance()) { 
ii.get() .print(); 


}; 

> 1 
2 
3 


ii.delete(); 
Transaction.end() ; 
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Iterators allow more flexibility than the scan statement—for 
example, you can process a collection from bottom to top and can 
have multiple iterators active on a collection at the same time. 
Here, the iterator is created so that it starts out at the bottom and 
is processed from bottom to top using advance(-1): 


Bag<Integer> xs; 

Iterator<Integer> ii; 

Transaction.start (); 

xs = Bag{1,2,3}; 

ii = xs.createIterator (FALSE) ; 

while (ii.advance(-1)) { 
ii.get() .print(); 


}; 
> 3 
2 
1 
ii.delete(); 
Transaction.end() ; 


The Empty Collection 


A collection with no elements is called an empty collection and is 
represented as Bag{}, List{}, or Set{}, depending on the kind of 
collection. 


When first created, a collection is not empty but NIL. A NIL 
collection represents a collection whose value is unknown, while 
an empty collection is a collection that is known to have no 
elements. It is often appropriate to initialize collections to empty. 
Collection-valued properties should usually be given a default 
value of empty. 


Using collections that are NIL rather than empty can have 
unexpected effects: 
Bag<String> ss; 


ss = ss.add("Singapore") ; 
ss.print(); 


> NIL 


This happens because adding an element to a NIL collection, like 
most other operations on NIL values, returns the value NIL. 
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To test whether a collection is empty: 


if ( ppl.count() ==0) { 


It is not possible to use a test of the form: 


if (ppl == Bag{} ) ... /* WRONG */ 
because the == operator is not applicable to collections. 


In embedded ODQL, it is also possible to use the macro 
ODB_ISEMPTY. (See the “Using Embedded ODQL” chapter.) 


Creating New Objects 


You create objects in ODQL using the method new(). For 


example: 

Location loc; 

loc = Location.new ( name := "London" ); 

Person p; 

Pp = Person.new ( surname := "Spencer", 
firstnames := Bag{ "William", "James" }, 
location := loc ); 


This creates two new objects in the database, a location and a 
person, and initializes some of their properties. The value 
returned by new() is a reference to the newly created object. 


The initialization of instance-level properties depends on 
whether the property was defined as mandatory in the class 
definition, and on whether it was given a default value. 
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The rules with respect to mandatory properties are as follows: 


Mandatory Not Mandatory 
Non-NIL default The property can be explicitly The property can be explicitly 
specified given a non-NIL value. If no given a value or set to NIL. If no 
explicit value is given, the explicit value is given, the 
property takes the default value _ property takes the default value 
given in the class definition. given in the class definition. 
No default The property must be explicitly | The property can be explicitly 
specified or NIL given anon-NIL value. If NILis givena value or set to NIL. If no 
specified as default specified, an error occurs explicit value is given, the 


property defaults to NIL. 


The values assigned to the properties of the new object must be 
represented as simple constants or variables (not expressions). 


Another consideration in initialization is whether the property 
was defined as unique. Since a unique property must have a 
distinct value for every instance of the class, the new object 
cannot be assigned a value that already exists. 


It is possible to defer checking of mandatory and unique 
constraints until the end of a transaction. This is achieved using 
the Transaction.setConstraintMode() method. If constraint 
checking is deferred, it is not necessary to specify a value for a 
mandatory property immediately in the new() method, provided 
that a value is supplied before the end of the transaction. 
Likewise, more than one unique property can temporarily have 
the same value, but the values must be unique before the 
transaction ends. 
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Updating Properties of Objects 


You update objects by using simple assignment syntax: 


Person p; 
p = Person.find("William James Spencer") ; 
p.jobTitle = "Documentation Manager"; 


The last line of this example modifies the jobTitle attribute of the 
person referred to by the variable p, setting the new value of this 
attribute to “Documentation Manager.” 


The same technique can be used to update class-level properties. 
In this case, you will generally use either the class name directly: 


Person.nextPersonnelNumber = 
Person.nextPersonnelNumber + 1; 


or a variable whose value is the class: 


Person class PC; 
PC = Person.getClass(); 
PC.nextPersonnelNumber = PC.nextPersonnelNumber + 1; 


If you are updating a collection-valued property, you can use a 
construct of the form: 


e.skills = e.skills.add("French") 


The effect of this construct is to retrieve the existing property, 
create a collection in the work store, modify it to create a new 
collection, and copy it back. For large collections, it is easier to 
carry out the update directly using directAdd() or 
directRemove(), as described in Adding and Removing Elements 
earlier in this chapter. 
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Deleting Objects 


Use of Metadata 


You delete objects by using the delete() method. For example: 


Person p; 
Pp = Person.find("Harold R Johnson") ; 
p.delete(); 


The standard delete() method only deletes the target object; it has 
no effect on other objects. If there are other objects related to this 
one that you want to delete or update at the same time, you can 
write your own version of the delete() method to achieve this. 


For example, when a Location is deleted, you might choose to set 
the location of all Persons currently based there to NIL. You can 
do this as follows: 


defineProcedure Void Location: :instance:delete() 
{ 

$Person p; 

$Bag<Person> pp; 

$pp = Person from Person 

where Person.location == self; 

$scan ( pp, p ) { p.location = NIL; }; 

$self.super: :delete() ; 

$return; 


}; 


Note: There can be other objects in the database that contain 
references to the object you have just deleted. If you attempt to 
follow these references, the result will be an error. It is up to you 
whether you want to clean up these references at the time the 
object is deleted, or to handle the errors when they occur. 


In Jasmine, information about classes, or metadata, is held within 
the database and is accessible at runtime using system-provided 
operations. For example, you can find out what class families are 
in the database, what classes are in each class family, and what 
the subclasses of each class are. This use of metadata is 
particularly relevant if you want to write an application that can 
run on a number of different databases. Examples of such 
databases are: 
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=» Acompletely general database (for example, if you are 
writing a report writer) 


=» Acustomizable database that might exist in many different 
variants or that can be customized by the user 


For example, if the application is about planned 
maintenance, the database might be able to handle 
maintenance of any kind of equipment, where each kind of 
equipment is represented by a class in the database. 
Furthermore, there can be parts of the application that do not 
know what classes of equipment are available. This can 
often be handled well through inheritance (class methods 
and class attributes can be very useful), but sometimes 
interrogating the metadata is the simplest approach. For 
example, you may want to display the list of kinds of 
equipment on the screen. To do this you could use: 
Bag<Equipment class> ECS; 

Equipment class EC; 


ECS = Equipment .getSubClasses () ; 
scan ( ECS, EC ) { EC.getClassName().print(); }; 


The methods provided by Jasmine to access metadata include the 
following: 


getAllClasses() getInsToClass() 
getAllFamilies() getMaxInstanceSize() 
getClass() getMethodInfo() 
getClassName() getMethodSource() 
getDescription() getPropNames() 
getFamilyName() getPropInfo() 


They are described in detail in the Reference guide. 


The method getClass() needs some explanation. In ODQL, a 
class name such as Person can only be used in contexts where a 
class name is explicitly allowed, for example, to invoke a 
class-level method. It cannot be used simply as a variable to 
refer to the class. For example, you cannot write: 


if ( p.getInsToClass() == Person ) { ... }; 
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because a class name cannot be used as a term in an expression. 
Instead you can write: 


if ( p.getInsToClass() == Person.getClass() ) 
{ ... }; 


Here the class name Person is used in the request 
Person.getClass(), which is the correct way to invoke a class-level 
method. The particular method getClass() returns an internal 
value representing the class it is applied to; this value can be 
assigned to a class variable or compared with another value 
representing a class (in this case, the value returned by the 
method getInsToClass(), which returns the class to which its 
target instance belongs). The effect of the example is to test 
whether the current value of the variable p is an immediate 
instance of the class Person. 
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7 Using Interpreted ODQL 


In This Chapter 


This chapter gives information about how to use interpreted 
ODQL. It covers the use of both ODQL statements and ODQL 
interpreter commands, and includes information about 
transaction control and error handling. 


Starting and Stopping the Interpreter 


Using the ODQL interpreter, you can enter ODQL statements 
and commands interactively or you can have them read from a 
file. The following is an example of a typical command to start 
the interpreter: 


codqlie -envFile client.env 


By default, the codqlie command uses a client environment file 
for the information needed to access the Jasmine server (for 
example, the hostName). You can specify the file name on the 
command line using the -envFile option, as in the example 
above, or use the JAS_ENVFILE environment variable to specify 
a default file name. 


ODQL Interpreter 


Version details 
Copyright details 


host02(systemCF) > 
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Note: The Jasmine server must be running before you can start 
the interpreter (refer to the “Starting and Stopping the Server” 
chapter of the Installation and Operations guide for information on 
how to start a Jasmine server). 


To stop the interpreter, enter the end command at the prompt, 
followed by a semicolon, as shown below: 


end; 


Types of Operations 


You can carry out the following types of operations using 
interpreted ODQL: 


s ODQOL statements 


ODQL statements can be used to execute queries against the 
database; to create, update, and delete database objects; and 
to invoke methods defined in the database. For an 
introduction to ODQL, see the “Using ODQL” chapter. The 
full syntax of ODQL is defined in the Reference guide. 


# ODQL interpreter commands 


ODQL interpreter commands are used to define and compile 
new classes and methods, and to control the execution of the 
ODQL interpreter. 
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The ODQL interpreter commands are shown below: 


Command Used For Results 
Displayed? 

addProcedure Adding procedures Yes 

buildClass Building classes Yes 

compileProcedure Compiling procedures Yes 

defineClass Defining classes Yes 

defineProcedure —_ Defining procedures Yes 

end Terminating ODQL No 
interpreter 

execFile Executing a file of ODQL Yes 
statements 

undefVar Canceling variable No 
declaration 


Note that statements in a host language, such as C or C++, 
cannot be executed in the ODQL interpreter. 


Entering Statements and Commands Interactively 


You input ODQL statements and ODQL interpreter commands 
after the prompt. Each command or statement must be 
terminated by a semicolon (;). 


The following example displays the names of all available class 
families, showing how a statement is entered interactively in the 
interpreter: 

FamilyManager .getAllFamilies() .print(); 

> Bag { mediaCF, jadelibCF, demoCF } 
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If you press Enter before the statement is complete, the system 
prompts with a question mark for continuation. Type the rest of 
the statement, including the terminating semicolon, and press 
Enter again. For example: 


FamilyManager.getAllClasses ("demoCF") .print () ; 


> Bag{ 
demoCF: :ApplicationObject, 
demoCF: :Project, 
demoCF: : Location, 
demoCF: :Person, 
demoCF: :Manager 


} 

You can enter several statements on a single line of input, each 
terminated by a semicolon. For example: 

Integer x,y,z; x = 10; y = 100; z =x * y; z.print(); 
> 1000 

The table in the topic Types of Operations shows for which 


commands the processing results are displayed. Processing 
results are also displayed when: 


=» Anerror has occurred after execution of an ODQL statement 
or ODQL interpreter command 


= print() or a similar method is executed 


Entering Statements and Commands from a File 


You can also create a file of ODQL statements, and execute this 
file either by using the -execFile argument of the codqlie 
command, or by using the execFile command within the ODQL 
interpreter itself. 


You can start a new line in the file anywhere a space can appear; 
you can also enter several ODQL statements on a single line. 
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Specifying a Default Class Family 


When you use a class name in ODQL, it can be qualified by a 
class family name in the form: 


cfname: :classname 
Note that there is no space between the colons. 


If you omit the class family name, the system will search for the 
class first in the current default class family and then in the 
system class family. 


When you start the ODQL interpreter, the default class—which 
is the class family name systemCF—is displayed by the ODQL 
interpreter as part of the prompt. You can change the current 
default class family by using the defaultCF declaration. The 
following example changes the default class family from 
systemCF to demoCF: 


defaultCF demoCF; 
defineClass Person ... 


Interrupt Proc essing 


Interrupt processing allows you to disable a process which is 
being executed and return to the previous status. To start 
interrupt processing, press Ctrl+C. What happens next depends 
on when you start interrupt processing: 
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When Started 


Between title display and first 
prompt display. 


Result 


The ODQL interpreter is 
terminated. 


After the prompt has been 
displayed and before any text 
has been entered. 


During input of continuous 
lines. 


During processing (after 
pressing the Enter key). 


Transaction Control 


The transaction is rolled back, 
and the interpreter is 
terminated. 


Processing is restored and a 
new prompt is displayed. 


Processing is restored and a 
new prompt is displayed. 


As a rule, the execution of one statement is regarded as one 
transaction. The transaction is automatically started and ended 
by the ODQL interpreter. Accordingly, when an ODQL 
statement or ODQL interpreter command is executed, a 
transaction is started, and is committed and ended when 
processing ends normally. When an error occurs due to the 
abnormal ending of a process, the transaction is rolled back and 


then ended. 


You can use methods to control the start, end, and rollback of a 
transaction. As shown in the example below, this allows a 

sequence of operations to be executed in a single transaction. Ifa 
failure occurs, the entire transaction will be rolled back. 


Transaction.start (); 
Bag<classA> xs; 
classA x; 
xs = classA from classA; 
scan(xs, x) { 

x.print (); 
}; 


Transaction.end() ; 


Start transaction 


One transaction 


End transaction 
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Not all ODQL interpreter commands can be executed within a 
transaction, which also means they cannot be rolled back. For 
example, the command compileProcedure must be executed 
outside a transaction. 


The following table summarizes which commands can and 
cannot be executed within a transaction. 


Command Executed Exec uted 
Within Outside Transaction 
Transaction 

addProcedure Yes Yes 

buildClass Yes Yes 

compileProcedure No Yes 

defineClass Yes Yes 

defineProcedure Yes Yes 

end Yes Yes 

execFile Yes Yes 

undefVar Yes Yes 


Another way to execute a number of statements within a single 
transaction is to use a block, although you cannot use ODQL 
commands within a block. A block is a sequence of ODQL 
statements separated by semicolons and surrounded by curly 
braces. A block entered directly at the interpreter prompt counts 
as a single statement and, therefore, as a single transaction. For 
example, the following will execute three statements as a single 
transaction: 


{p.grade = 12; p.salary = 19000.00; p.bonus = NIL}; 


Transactions cannot be nested; you cannot start a transaction if 
there is already a transaction active. 


You can identify a transaction as read-only by specifying the 
appropriate parameter for the Transaction.start() method. 
Read-only transactions operate without locking. 
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Enor Handling for ODQL Statements 


In the ODQL interpreter environment, errors which occur when 
ODQL statements are being executed are handled as follows: 


« When the processing of an ODQL statement fails, the 
transaction is rolled back and the interpreter prompt is 
displayed, ready for you to input the statement again 


To prevent simple typing mistakes causing a large amount of 
work to be rolled back, it is best to execute any complex 
statements from a file. 


« If anerror occurs and processing cannot continue, the ODQL 
interpreter environment is terminated 


The Jasmine server rolls back the transaction to its status 
before the error was detected. This allows the database that 
was being used to be recovered. 


If any failure occurs preventing the interpreter from continuing, 
the Jasmine server rolls back any transaction that was active at 
the time, and releases locks. 


For further information on error handling, refer to the Reference 
guide. 


Dealing with Deadlocks 


When a deadlock is detected during the execution of the ODQL 
interpreter, Jasmine rolls back the transaction and displays an 
error message, showing that a deadlock has occurred. 


If the execFile command is executing batch commands, detection 
of a deadlock stops the execution of the command and ODQL 
returns to its prompt. 
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If a deadlock arises under the following circumstances, Jasmine 
automatically rolls back the transaction. After the transaction is 
rolled back, processing continues, with the interpreter 
automatically starting and stopping a transaction for each 
subsequent statement. 


=» A deadlock occurs when you execute ODQL statements by 
redirecting the standard interpreter input. 


a Either: 
-— You have used Transaction.start() to start a transaction. 


-— You are executing a compound statement. 
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3 Using Embedded ODQL 


In This Chapter 


This chapter gives general information about embedded ODQL 
and information about how to use embedded ODQL in methods. 


What Is Embedded ODQL? 


ODQL statements can be embedded in code written in a host 
language, specifically in C or C++. Embedded ODQL is used 
within the code of methods, defined using the defineProcedure 
and addProcedure commands, and can also be used in separately 
compiled modules that are called from methods. 


As far as ODQL is concerned, there are no significant differences 
between C and C++. The way ODQL statements are 
embedded—and the way ODQL variables are mapped to host 
language variables—is the same in both cases. 


There are some simple rules governing the way embedded 
ODQL interacts with the host language: 
s ODQL and host language statements can be freely mixed 


ODQL statements are distinguished by an initial $ sign. 
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# ODQL variables can be mapped to a pair of host language 
variables 


One of these variables holds the value of the ODQL 
statement, the other holds its status (VALID, NIL, or 
ERROR). 


= Except in macros (see below), ODQL variables can be 
referenced only in ODQL statements, and host language 
variables can be referenced only in host language statements 


= Jasmine provides a number of macros that can be used in 
host language statements 


In some cases these macros expect ODQL variables as their 
parameters. 


Note that when using C++, the system does not require any 
correspondence between Jasmine classes and C++ classes. Of 
course, you may choose to provide such a correspondence 
yourself. 


There is a great deal of overlap between the capabilities of ODQL 
and the capabilities of the host language, and in many cases you 
have a free choice of which language to use. This depends 
largely on personal preference. However: 


s ODQL is always needed to access the database 


= The host language is used to perform computations that are 
more complex than ODQL can handle, or to invoke external 
functions (for example, operating system calls). 
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Whiting Embedded ODQL Declarations and 


Statements 


An embedded ODQL variable declaration can occur anywhere a 
host language variable declaration could occur. An embedded 
ODQL statement can occur anywhere a host language executable 
statement can occur. Host language statements can be nested 
inside blocks within ODQL statements, and vice versa. 


ODQL provides an if statement and a while statement that are 
equivalent to the corresponding host language constructs. 


If the Boolean condition in the if or while statement references 
host language variables, a host language if or while statement 
should be used. On the other hand, if it references ODQL 
variables, an ODQL if or while statement should be used, that is, 
it should be prefixed with a $ sign. 


ODQL and host language statements can be freely mixed in the 
body blocks of the if or while statement, regardless of whether 
if/while or $if/$while is used. For example: 


$Boolean b <bval, bstat>; 
$String s[40] <sval, sstat>; 


$if (b) { 
$p = Person.find("John Carter") ; 
$s = p.surname; 
if (sstat == ODB_STATNIL ) { 
printf("Surname is NIL\n"); 
} else { 


printf("Surname is %s\n", sval); 
} 
}; 


Similar considerations apply to the scan and indexScan 
statements. In this case, the scan or indexScan statement itself is 
always an ODQL statement and always starts with a “$”. The 
statements within the iteration block, however, can be host 
language statements or ODQL statements. 
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Variables in Embedded ODQL 


ODQL variables can be referred to only in ODQL statements, 
while host language variables can be referred to only in host 
language statements. 


To communicate between the ODQL and host language parts of 
the application, you can declare a mapping between ODQL 
variables and host language variables. For example, the 
following ODQL declaration declares a mapping between the 
ODQL variable n and the two host language variables nval and 
nstat: 


$Integer n <nval, nstat>; 


The first host language variable represents the value of the ODQL 
variable, the second represents its status. The status is either 
ODB_STATVALID, ODB_STATNIL, or ODB_STATERROR. 
ODB_STATNIL indicates that the ODQL variable is currently 
NIL. ODB_STATERROR indicates that the most recent 
assignment to the ODQL variable generated an error value. 


To read the value of an ODQL variable from the host language, 
first check that the status variable is ODB_STATVALID, and then 
test the value variable. For example, the following code scans all 
Persons in the database, testing each one to see if the surname 
begins with a lower case letter: 


$Bag<Person> pp; 
$Person p; 
$String s <sval, sstat>; 
$pp = Person from Person; 
$scan ( pp, Pp) { 
$s = p.surname; 
if (sstat == ODB_STATVALID) { 
if (islower(*sval)) { 


}; 
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To write to the value of an ODQL variable from the host 
language, first set the value variable, and then set the status 
variable to ODB_STATVALID. For example: 


sval = "Jackson", 
sstat = ODB_STATVALID; 
$p.surname = s; 


ODQL variables can also be declared without corresponding host 
language variables. In this case, they can only be accessed within 
ODQL statements. 


Data Type Mappings 


The only ODQL variables that can be mapped to host language 
variables are the atomic literal types—Integer, Real, Boolean, 
String, Date, and ByteSequence—and variables referring to 
user-defined entities. Decimal variables cannot be represented in 
the host language; neither can collection-valued variables nor 
class variables. The mapping of ODQL types to host language 
types is as follows: 


ODQL Variable Types Host Language Variable Types 


Integer long 

Real double 

String char * 

ByteSequence ODB_BYTESEQ 

Boolean char 

Date ODB_DATE 

Decimal Cannot be specified as a host variable 
User-defined class ODB_OBJECT_ID 


The host language variables (nstat and nval in the example 
below) are declared automatically with the correct data type. 


$Integer n <nval, nstat>; 
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The type ODB_BYTESEQ is defined as follows: 


typedef struct { 

long length; 

unsigned char *byteseq; 
} ODB_BYTESEQ; 


Here length is the length of the data, and byteseq is the address of 
the data. 


The type ODB_OBJECT_ID is defined as follows: 


typedef struct odb_object_id { 
unsigned char cfname[34]; 
unsigned short cno; 
unsigned long ino; 

} ODB_OBJECT_ID; 


By mapping the object identifier of a Jasmine object to a data 
structure in the host language program, you can save object 
identifiers in some external place under application control and 
retrieve the objects later when required. For example, you could 
store Jasmine object identifiers in an external relational database. 
Object identifiers are guaranteed to remain stable during the life 
of the object. 


For example, in embedded ODQL, a host language variable can 
be mapped to an ODQL variable representing an entity: 


$Person p <pval, pstat>; 


The type of pval is ODB_OBJECT_ID; this is a defined structure 
with components representing the class family name, class 
number, and instance number. This provides a supported way 
of remembering object identifiers outside the Jasmine system for 
later use. 


Handling Strings and ByteSequences 


For ODQL Strings and ByteSequences, a maximum length can 
optionally be given. For example: 


$String[10] s <sval, sstat>; 
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If no length is given, the system automatically allocates space to 
each String or ByteSequence when a new value is assigned to the 
ODQL variable. For example: 

$String s <sval, sstat>; 

$String t <tval, tstat>; 

$s = "South "; 

$t = "America"; 

$s = s.stringCat (t) ; 


Here the system initially allocates enough space to hold the 
values “South” and “America” to the two variables s and f. 
When s is assigned a larger value in the final line of the example, 
additional space is allocated; this may or may not cause the 
string to be moved. If it is moved, the char * pointer in sval 
changes, and any other host language pointers to the string 
become invalid. 


If both host language variables and a length are specified, the 
space for the variable must be allocated by the user by assigning 
a pointer value to the host language char* variable. The ODQL 
variable cannot be referenced until this has been done. For 
example: 

char t[14]; 

strcpy(t, "South America") ; 

$String [14] s <sval, sstat>; 

sval = t; 

sstat = ODB_STATVALID; 

$s = "North America"; 


You should count the terminating NULL (or \0) character of a 
string as part of the length. 


A new value can be assigned to the ODQL variable provided it 
fits in the space available at this address. The size of the area 
available is assumed to be that given in the length specification 
of the declaration. 


In the case of a String, the host language representation of the 
string has a terminating NULL character (\0) in the normal way. 
In the case of a ByteSequence, NULL bytes can appear at any 
position in the ByteSequence, and the length is determined by 
the length field of ODB_BYTESEQ. 
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Note: You can also specify the maximum length of Strings and 
ByteSequences in contexts other than for a variable in embedded 
ODQL—for example, in attribute definitions and in the 
parameters and return class of methods. In all cases, the 
maximum length is optional and defaults to 65536. See Editing 
Property Definitions in the “Modifying the Structure of a 
Database” chapter for further details. 


You can concatenate Strings and ByteSequences using the 
stringCat() and byteSequenceCat() methods, respectively. If you 
try to assign the resulting string directly to a variable that has 
been declared with a maximum length and the result exceeds the 
maximum length, the string is truncated so that it fits into the 
length. However, if you assign the result to an attribute of an 
entity and the maximum length is exceeded, an error is reported. 


Note that you can specify a maximum length for single-valued 
attributes, variables, and parameters, but not for 
collection-valued values. 


Embedded ODQLand the Host Language 


Preprocessor 


Embedded ODQL is compiled by first translating it into host 
language statements, then compiling the resulting host language 
program using the standard C or C++ compiler. 


C and C++ compilers invariably include a preprocessing phase to 
interpret directives, such as #define, #include, and #ifdef. This 
preprocessor is executed after the translation of ODQL 
statements, which means that the host language preprocessor 
cannot be used to influence ODQL translation. For example, 
ODQL variable declarations cannot be included in .h files. 
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The main uses for dynamic ODQL are: 


Using Dynamic ODQL 


= Toexecute ODQL commands, such as defineClass, from 


embedded ODQL 


ODQL commands are always interpreted; embedded ODQL 
allows only ODQL statements (not commands) to be 
embedded in the host language. The execute statement can 
be used from embedded ODQL to cause a particular 
command to be executed by the interpreter. 


= Toconstruct a query or another statement, such as new(), 
from input supplied at execution time 


Commands in Embedded ODQL 


You can use all ODQL statements and declarations in embedded 
ODQL. However, you cannot use ODQL commands directly. It 
is possible to issue most of these commands from embedded 
ODQL by encoding them as character strings and using the 
execute statement. The following table shows which commands 
can be used in an execute statement, and also indicates in each 
case whether this can be within a transaction, outside a 


transaction, or both: 


Command Used For execute Statement 
Within Outside 
Transaction Transaction 
addProcedure Adding procedures Yes Yes No 
buildClass Building classes Yes Yes No 
compileProcedure | Compiling procedures Yes No Yes 
defineClass Defining classes Yes Yes No 
defineProcedure Defining procedures Yes Yes No 
end Terminating ODQL No -- -- 
interpreter 
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Command Used For exec ute Statement 
Within Outside 
Transaction Transaction 
execFile Executing a file of ODQL Yes Yes Yes 
statements 
undefVar Canceling variable No -- -- 
declaration 


The following example executes the compileProcedure command 
using embedded ODQL: 
$String s; 


$s = "compileProcedure Person"; 
Sexecute s; 


Dynamic Execution of ODQL Statements 


It is also possible to construct an ODQL statement as a string and 
execute it using the execute statement. This is useful, for 
example, if you want to construct a query based on a value 
supplied at execution. For example, the variable condition in the 
code below might be supplied as a parameter: 

$String query; 

$Bag<Person> pp; 

$query = String.format ("pp = Person from Person 


where %s;", condition) ; 
Sexecute query using pp; 


The condition parameter, which would have a value like 
“Person.grade > 10” could be entered by a user from a client 
application or read from a file or environment variable. 


The using clause of the execute statement is needed to establish a 
correspondence between the variable pp in the executed 
statement and the variable pp in the calling code. 


The contents of the string passed to the execute statement must 
be an ODQL statement or command, including its terminating 
semicolon. 
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A number of macros are available to make programming in 
embedded ODQL easier. These macros are all provided for use 
in host language statements. They include: 


Type 
Data type definition 


Name 


ODB_BYTESEQ 
ODB_OBJECT_ID 


Macrosin Embedded ODQL 


Used For 


Defining structure of host 
language variables corresponding 
to ODQL data types 


Error processing 


Error evaluation 


Error message 
handling 


ODB_ERRORRETURN 
ODB_PROCERRGOTO 
ODB_PROCERRGOTORESET 


ODB_CODE 
ODB_DETAIL 
ODB_ERRORCODE 
ODB_ISERROR 


ODB_DETAILMESSAGE 
ODB_MESSAGE 
ODB_MESSAGELEVEL 


Specifying what should happen if 
an error occurs 


Evaluating the error that has 
occurred 


Transmitting an error message to 
a user or printer 


Host variable status 


ODB_STATERROR 
ODB_STATNIL 
ODB_STATVALID 


Getting or setting the status of 
ODQL variables 


Object deletion ODB_ISDELETED Checking whether an object 
checking assigned to an ODQL variable is 
deleted 
Status checking ODB_ISNIL Testing values for NIL or empty 
ODB_ISEMPTY 
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Whiting Methods with Embedded ODQL 


Using defaultC F in 


You define the body of a method in C or C++ with embedded 
ODQL statements. 


You use the language: specification of the commands 
defineProcedure and addProcedure to specify whether the body 
of the method is written in C or C++ with embedded ODQL 
statements or in pure ODQL. By default the system assumes that 
a method is written inC. The defineProcedure command and 
the other commands used to define classes and methods are 
described in the “Setting up a Database” chapter. The 
addProcedure command is described in the “Modifying the 
Structure of a Database” chapter. This chapter is concerned with 
how you write the ODQL code within a method. 


The following example shows a method written entirely in 
embedded ODQL with no C or C++: 


defineProcedure ...... 

{ 
$Decimal [8,2] value; 
$value = self.unitCost * self.quantity; 
$return (value) ; 


}; 


Methods 


The default class family used by the class names within a method 
is often given by a defaultCF declaration occurring at the start of 
the method body. A defaultCF that is outside the method body 
has no effect on the code inside the method body, and vice versa. 


You can also specify a default class family using the -defaultCF 
option to the compileProcedure command. This overrides any 
$defaultCF declarations within the source of the methods. 
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The Variable self 


Within a method, the variable self is always available to refer to 
the target of the method. For an instance-level method, this will 
be the object on which the method was invoked; for a class-level 
method, it will be the class. 


For example, the following method tests whether the person to 
which it is applied is an instance of the class Manager: 
defineProcedure Boolean Person: :instance:isManager () 
{ 

$return (self.getInsToClass () ==Manager.getClass()); 


, 


Retum from a Method 


A method should always exit using the ODQL return statement 
with a $ sign. Do not use the host language return statement, 
and do not allow implicit exit by dropping off the end of the 
code. 


The return value must be of the data type declared as the result 
type of the method. 


Note that, unlike C, the parentheses around the return value are 
mandatory. 


Important! You should never exit from a user-defined method using 
the standard C library function exit(), nor should you call other 
functions, such as abort() or fork(), that affect the process as a whole. 
Jasmine will not prevent you from calling these functions, but doing so 
can have severe repercussions. For example, calling exit() or abort() 
will terminate the Jasmine server process. 
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Refining an Inherited Method 


One of the benefits of Jasmine is the ability to define 
polymorphic operations, that is, operations that are implemented 
by different methods in different classes. In particular, a 
common requirement is for a subclass to redefine a method 
inherited from its superclass. 


The refined method must be included in the class definition of 
the subclass. This can be achieved either by including it 
explicitly in the defineClass statement for the subclass, or by 
adding it to the class definition later using the addProcedure 
command. The interface to the method—that is, its name and the 
names and types of its parameters—must be exactly the same as 
for the corresponding method on the superclass, and the return 
type must be the same as or a subclass of the original return type. 


The refined method can be written in exactly the same way as 
any other method. However, the need frequently arises for the 
redefined method to invoke the original method. For example, 
suppose there is a method annualLeave() to calculate a person's 
leave entitlement, and the rule is that a Manager gets an extra 
five days leave by virtue of being a Manager. Then the method 
annualLeave() for a Manager needs to invoke the ordinary 
method annualLeave() for a Person and add an extra five days. 
We, therefore, need a construct that says “invoke the method 
annualLeave() as if this object were a Person rather than a 
Manager.” 


This is done by qualifying the method name with a class name: 
defineProcedure Integer 


Manager: : instance :annualLeave () 


$return( self.Person: :annualLeave() + 5 ); 


, 


The keyword self here refers to the target of the method being 
executed, that is, to the manager whose annual leave is currently 
being calculated. 
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If you simply invoked self.annualLeave() directly without 
qualifying it with the class name Person, the method would call 
itself and loop indefinitely. Instead, the qualifier Person tells the 
system you want to use the version of annualLeave() that would 
be used if the manager were an ordinary Person and not a 
Manager. 


If Manager has only one superclass, you could also use the 
keyword super rather than naming the superclass explicitly. 


This construct—qualifying a method name with a class name to 
override the usual rules for method selection—can be used 
anywhere in ODQL, but its only real value is in the context of 
redefining a polymorphic method. 


Using the Host Language Preprocessor in a Method 


Within the code of a method, you can use preprocessor directives 
such as #include and #define. These are expanded after ODQL 
translation, so they cannot be used to include ODQL statements 
or to affect the expansion of ODQL statements. 


An example is shown below: 


defineProcedure Integer Person: :instance: seniority () 
language: "c" 


#define SENIOR 5 
#define JUNIOR 2 
$Integer x <xc, xs>; 
$if ( self.grade > 10 ) { 
xc = SENIOR; 
} else { 
xc = JUNIOR; 
}; 
xs = ODB_STATVALID; 
$return ( x ); 
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Some header files for C or C++ (for example, declarations of 
external functions) can cause errors or warnings when you 
include them in methods. This is because ODQL methods are 
converted into C or C++ functions, and the #include statements 
are within these functions. To avoid this type of error, you can 
use #odb_header as shown in the following example: 


#odb_header #include <stream.h> 


Lines headed by #odb_header are moved so that they appear in 
the generated C/C++ program before the function. It is, 
therefore, better to specify #odb_header for #include or #define 
statements as shown in the following example: 


defineProcedure Void Person: : instance: sayHello() 
language: "c++" 
{ 
#odb_header #include <iostream.h> 
#odb_header #include <iomanip.h> 
cout << "Hello" << endl; 
$return; 


}; 


Note that #odb_header must be placed at the beginning of a line 
and that there must not be any white spaces either before or after 
the hash (#) sign. 
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9 Setting up a Database 


In This Chapter 


This chapter provides detailed instructions on how to define a 
database. The flowchart below summarizes the tasks involved: 


Requirements and design 
information 


Define a store 


Define a class family 


Define the classes 


IE 


Implement the methods 


Implementing the application and 
populating the database 
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Defining a Store 


This section explains how to define a user store. All of the 
commands described require the Jasmine server to be running. 
See the “Starting and Stopping the Server” chapter of the 
Installation and Operations guide for details of how to check that a 
server is running and on how to start a server. 


Using the createStore Command 


Defining a user store is the task of reserving on disk the actual 
file space to be used to store user data. You create a store by 
using the system command createStore. The command generates 
and initializes the new store using the specified file name. 


The following example shows how you would use createStore to 
create the project store if operating in a UNIX environment: 
createStore -numberOfPages 2000 -pageSize 8 

project /usr/jasmine/stores/proj_ex1 


If operating in a Windows NT environment, the command 
would be: 


createStore -numberOfPages 2000 -pageSize 8 
project c:\jasmine\stores\proj_ex1 

This example shows the options and arguments required by 

createStore, as well as some that are optional: 


= The size of the store 


You determine the size of the store by specifying the page 
size (-pageSize) and the number of pages (-numberOfPages). 
If the requirements of the store change, you can increase the 
size using extendStore. 


s Thename by which the store is to be known 


You specify this using the storeName argument which, in this 
example, is project. 
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s The name of the file that Jasmine will use to create the store 


You specify this using the fileName argument which in the 
NT example is c:\jasmine\stores\proj_ex1. You can specify 
multiple file names in order to have the store span multiple 
drives. 


Note: Although it is recommended that you create a user store 
for storing your class families, it is not a requirement. If it suits 
your needs, you can store your user-defined class families in the 
system store as described in Using the createcf Command later in 
this chapter. 


Using Other Store Commands 


If you need to delete a store, you can do this using the system 
command deleteStore. For example, to delete the store project 
created in the previous example, you would enter: 


deleteStore project 


If you need to extend the size of a store, use the system 
command extendStore. This command lets you add more pages 
(of the same size specified by createStore). For example, to add 
five hundred pages to the store project created in the previous 
example, in a UNIX environment you would enter: 


extendStore -numberOfPages 500 
project /usr/ jasmine/stores/proj_ex2 


If operating in a Windows NT environment, the command 
would be: 


extendStore -numberOfPages 500 
project c:\jasmine\stores\proj_ex2 
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To display information about a store, such as its page size, 
number of pages allocated, and number of pages used, use the 
system command listStore. With this command, you can list 
information for a specific store, as in this example: 


listStore project 


You can also list information about all stores, simply by omitting 
the storeName argument. 


Defining a Class Family 


Before you can begin to define classes and methods and to store 
data in a store, you need to define a class family. You can either 
define the class family to be part of a user store or as part of the 

system store. 


Using the createcf Command 


You define class families using the system command createcf. 
When you specify the createcf command, you must include: 


=» The name of the class family you are creating 


= The name of the store in which the class family is to be 
stored 


For example, to create the projectCF class family in the project 
store, created previously using createStore, you would type the 
following: 


createcf projectCF project 
Instead of specifying the name of a user store, you can specify 
the system store, as shown below: 


createcf projectCF system 
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Although storing user-defined class families in the system store 
is an option, it is not often recommended. In most cases, you will 
find that the greatest flexibility is gained by creating a separate 
user store for each class family you define. This way, you can 
individually optimize the page size needed for storing each class 
family and can easily place the stores on separate devices. 


If you subsequently need to delete a class family, use the deletecf 
command. 


Class Family Names, Access Names, and Aliases 


A class family can have three different types of names: 


Original name 


The original name is the name supplied when you define the 
class family using the createcf command. You cannot omit 
the original name from the command specification. 


Access name 


A class family also has an access name that you can use to 
refer to a class family in place of its original name. The 
access name is defined in the CF environment parameter in 
the client environment file. For example, if the original name 
of a class family is testCF, and you specify the name 
mytestCF as the access name for the class family in your 
client environment file using the CF parameter, you can then 
access the class family by using the name mytestCF. Another 
user might use another name for this class family in their 
client environment file. 


Alias name 


You can optionally specify an alias name for a class family as 
an argument to the createcf command. You can use the alias 
name as the access name by specifying the alias name as the 
access name in the client environment file. If you do specify 
an alias name using createcf, you cannot specify any name 
except this alias name as the access name. 
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An example of when you can use access names is to have two or 
more class families with the same structure but different content. 
For example: 


= One store might contain live data and the other test data 


= One store might contain this year’s sales data and the other 
last year’s 


The way to achieve this is to have two stores and two class 
families. The two class families have different original names 
but the same alias name. When your application runs, it uses 
this alias name as the access name for the class family, and the 
client environment file determines which original class family 
the access name refers to. 


Here is an example of what you would do to set up a 
liveProjectCF and a testProjectCF containing the same classes: 


1. Set up a file of ODQL containing the class definitions. The 
file might be called classdefs.odql, and be structured like 
this: 


defaultCF projectCF; 

defineClass Person { ...}; 
defineClass Project { ...}; 
defineProcedure Decimal [8,2] 
Person: :instance: spendingLimit () 
{}; 

buildClass Person Project; 
compileProcedure Person Project; 


2. Create two stores, each containing a class family with alias 
name projectCF, as follows: 
createStore -numberOfPages 1500 -pageSize 8 
test c:\jasmine\stores\test 
createStore -numberOfPages 1500 -pageSize 8 
live c:\jasmine\stores\live 
createcf testProjectCF test projectCF 
createcf liveProjectCF live projectCF 
3. Create two client environment files called live.env and 
test.env. The first contains the line: 


CF projectCF liveProjectCF 
The second contains the line: 


CF projectCF testProjectCFr 
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Load the class definitions into both the class families: 


codqlie -envFile live.env -execFile classdefs.odql 
codqlie -envFile test.env -execFile classdefs.odql 
In the first case, the CF environment parameter ensures that 
all references to projectCF are interpreted as references to 
liveProjectCF so the new classes are defined within class 
family liveProjectCF; in the second case, the new classes are 
defined within testProjectCF. 


The system now contains two class families that have exactly 
the same classes and methods. If you always use the access 
name projectCF as the class family name to qualify class 
names such as Person and Project, either by explicit 
qualification (for example, projectCF::Person) or using a 
defaultCF directive, then: 


« Ifyou are running with the client environment file 
live.env, you will access data in the projectCF class 
family stored in the live store 


« Ifyou are running with the client environment file 
test.env, you will access data in the projectCF class 
family stored in the test store 


Defining the Classes 


By this stage, the classes you need should have been identified 
by the design process discussed in Logical Database Design in 
the “Designing a Database” chapter. It is now a question of 
entering the information. 


During this step of the process of setting up a database, you need 
to define all the classes in the class family. The class definition 
contains all the information that someone needs in order to use 
the class: 


A definition of all the properties (attributes and 
relationships) of the class 


A specification of the parameters and return type of each of 
its methods 
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Besides defining a class, you need to build the class, add the code 
to implement its methods, and compile the class. Building a class 
validates that all the definitions are consistent with each other, 
and allows instances of the new classes to be created in the store. 
Compiling a class generates a library of executable code so that 
the methods can be invoked. 


The process of establishing a class in ODQL consists of three 
main stages: 


« Defining the class in interpreted ODQL using the defineClass 
command 


= Building the class using the buildClass command 


=» Coding and compiling methods using the defineProcedure 
and compileProcedure commands 


This section describes how to establish classes using ODQL, with 
details regarding implementing methods and compiling the class 
described in the following section, Coding and Testing Methods. 
You can also establish classes and methods using Jasmine Studio, 
as described in the Jasmine Studio online help. 


It is possible to enter the class definition interactively at the 
terminal, but this is very error prone: a single typing mistake will 
invalidate the command. It is usually better to set up the class 
definition in a separate file of ODQL using a text editor, and to 
execute this file from the ODQL interpreter using the execFile 
command. Any errors can then be corrected with the text editor. 


Class definitions specified using the defineClass command can 
contain the following elements: 
=» Class name 


You must include a class name in the class definition. 
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Superclass specification 


Specify the names of the superclasses of the new class, 
preceded by the keyword super:. If the only superclass is the 
system class Composite, you can leave this out, although you 
may prefer to include it for documentary reasons. 


Class description 


This is optional. A description is preceded by the text 
description: and is enclosed in double quotation marks (“ ”). 


Properties for the class 
The property specification can include: 


- Whether this is a class-level or instance-level property 
(class-level properties are grouped under the heading 
class: and instance-level properties are grouped under 
the heading instance:) 


— The data type of the property (including whether it is 
single-valued or collection-valued) 


- The property name 

-  Adescriptive comment 

— Whether the property is mandatory 

— Whether the property is unique 

-— Optionally, a default value for the property 
Method specifications 


You can specify class-level methods, class-collection-level 
methods, instance-level methods, and 
instance-collection-level methods. The method specification 
includes the definition of the return type of the method, as 
well as the names and data types of its parameters. 


There are two possible approaches to handling class family 
specifications in the defineClass command: 


1. 


Precede the defineClass command with a defaultCF 
declaration for the class definition it is in. 


Then you only need to qualify any class names that are not in 
this class family or in the system class family. 
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Example 


defaultCF demoCF; 


defineClass 


2. Give all class family names other than systemCF explicitly; 
wherever a class name is used, it is qualified with the class 
family name. 


Which of these two approaches you use is largely a matter of 
personal preference. 


An example of an ODQL class definition is shown below. Note 


that this example uses the first of the two approaches for class 
family specifications described previously. 


Person 


super: ApplicationObject 
description: "Holds details of a person" 


{ 
maxInstanceSize: 4; 
class: 
Integer 
Person 
instance: 
Integer 
String 
Bag<String> 
default: Bag{}; 
Location 
String 
String 
String 
Integer 
Manager 
mediaCF: :Bitmap 
String 
String 
Decimal [8, 2] 
Void 
Bag<instance>: 
Boolean 


}; 


nextPersonnelNo default: 0; 
find( String name ); See Note 1 


personnelNo unique: ; See Note 2 
surname mandatory: ; See Note 3 
firstnames 

See Note 4 
location; 
phone; 
email; 
jobTitle,; 
grade; 
boss; See Note 5 
photograph; 
name () ; 
shortName () ; 
spendingLimit () ; See Note 6 
allocatePersonnelNo () ; 


coLocated () ; See Note 7 


Notes: 


1. find() is a class-level method that takes a single parameter of 
type String and returns an instance of the class Person. 


2. personnelNo is an instance-level, single-valued attribute of 
type Integer. It is a unique attribute. 


3. surname is an instance-level, single-valued attribute of type 
String. It is a mandatory attribute. 
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4.  firstnames is an instance-level, collection-valued attribute of 
type String collection. By default, the collection is empty. 


5. boss is an instance-level, single-valued relationship with the 
class Manager in the class family demoCF. 


6. spendingLimit() is an instance-level method that has no 
parameters and returns a Decimal literal. 


7. coLocated() is an instance collection-level method that has no 
parameters and returns a Boolean value of TRUE if all 
persons in the collection are at the same location or if the 
collection is empty. 


A class definition contained in a defineClass command typically 
refers to other classes, for example, the superclass of the new 
class, and any classes referred to by relationships within the 
definition. It is not necessary for these classes to exist at the time 
you issue the defineClass command. This is because you may 
want to define circular relationships: the Project class might have 
a relationship to Person while the Person class also has a 
relationship to Project. 


Before you can use a class definition, you must build the class 
using the buildClass command. At the time you build a class, all 
the other classes it refers to must be defined. 


As with the defineClass command, there are two possible 
approaches to handling class family specifications in the 
buildClass command. Again, which of these two approaches 
you choose is largely a matter of personal preference. 


The following example shows how to build the Person and the 
Project classes in the demoCF class family using the approach of 
defining the class family names explicitly: 


buildClass demoCF::Person demoCF: :Project; 


Separate class names with blank characters when you are 
building a number of classes at the same time. 


Setting up a Database 9-11 


Defining the Classes 


Setting up a File of Class Definitions 


It is often simplest to set up all the class definitions for a class 
family in a single ODQL file. This might take the following form: 
/* Definitions of classes for the 

demoCF class family 

Version 1.1 

Date 30 September 1997 

Author Cormac McKenna */ 


defaultCF demoCF; 
defineClass ApplicationObject super: Composite 


defineClass Project super: ApplicationObject 
defineClass Person super: ApplicationObject... 
defineClass Manager super: Person 

defineClass Location super: ApplicationObject 


buildClass ApplicationObject Project Person Manager 
Location 


Such a file can be executed either directly from the codqlie 
command using the -execFile option on the command line, or by 
entering codqlie interactively and using the ODQL execFile 
command. If building the classes fails because you have made 
an error, you can correct the error using a text editor and 
resubmit the whole file. 


There may be warnings that you are redefining classes that 
already exist, but you can safely ignore these. If, however, you 
want to make changes after you have successfully built the 
classes—perhaps after compiling methods or creating 
instances—you will need to delete the classes first. 


In the above example, you can achieve this simply using the 
ODQL statement: 


ApplicationObject .delete() ; 
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This deletes the class ApplicationObject, all its instances and 
methods, all its subordinate classes, and all their instances and 
methods—which in our example represents the entire contents of 
the database. 


Important! Do not do this unless you can rebuild the classes and 
methods from a file of ODQL. 


Coding and Testing Methods 


The class definitions contain the specifications of methods 
available for the class: that is, a definition of the name of the 
method, the names, types, and default values of the parameters 
to the method, and the type of its result. The next stage is to 
write code defining the implementation of the methods. 


You can do this using the ODQL interpreter. The code is, in 
general, written in C or C++ with embedded ODQL statements. 
The source code is stored in the store and can be retrieved using 
the getMethodSource() operation. 


The way you write methods using ODQL embedded in C or C++ 
is explained in the “Using Embedded ODQL” chapter. The 
following sections explain how you can use the ODQL 
interpreter to enter this code and compile it. 


Using the ODQL Interpreter to Code and Compile a Method 


This section explains how to code and compile a method using 
the defineProcedure, addProcedure, and compileProcedure 
commands. 
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Defining a Method in ODQL 


The usual way of defining methods in ODQL is to include the 
specification of the method—that is, its name, its return type, and 
the names and types of its parameters—in the class definition, 
and then to define the implementation of the method (the code to 
be executed) separately using the defineProcedure command. 


An alternative is to omit the specification from the class 
definition and to define both the specification and the 
implementation using the addProcedure command. The 
advantage of addProcedure is that you can use it at any time 
after the class is defined, without having to go back and change 
the class definition. 


As with class definitions, you will probably find it useful to enter 
the defineProcedure and addProcedure commands from a file 
rather than entering them interactively at the terminal. 


Tip: There are various ways you can organize these files. 
One approach is to have one file containing all the method 
definitions for a single class. With a large and complex 
project you may prefer to divide things up further, so that 
each method definition is in a file of its own. The grouping 
of methods into classes can then be reflected in the structure 
of the directories used to hold these files. It is also possible 
to set up a file for the class containing execFile commands 
for each of its methods. 


Methods specified using the defineProcedure and addProcedure 
commands can contain the following elements: 


= Data type of the value returned by the method 
For example, if the returned object is an integer, you specify: 
defineProcedure Integer 


The data type is specified in the same way as for a variable 
declaration. For example: 
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Data Type Value 
Integer The method returns an integer. 
Bag<String> The method returns a bag of strings 


(other kinds of collections, such as 
Array, Set, and List, can also be 


specified). 
Person The method returns a Person. 
Person class The method returns the class Person 


or aclass subordinate to Person. 


Bag<Person class> = The method returns a bag of classes, 
each of which is either Person or one 
of its subordinates (other kinds of 
collections, such as Array, Set, and 
List, can also be specified). 


If the method returns no value, specify the returned data 
type as Void. 


The returned data type must either be an atomic literal or a 
user entity. It cannot be a tuple or a system-defined entity 
class. However, note that the classes in a class library such 
as the multimedia class library are considered to be 
user-defined classes. 


Method identification 


To identify a method uniquely you must identify the class, 
the level of the method, and the name of the method. The 
class name itself is optionally qualified by the class family 
name. For example, you would define the method 
getDirectReports() in the Person class like this: 


defineProcedure Bag<Person> 
Person: :instance: getDirectReports () 


Here a collection of Person objects is the returned data type 
and Person::instance: getDirectReports() is the method 
identification. Person indicates that this is a method defined 
on the Person class; instance identifies it as an instance-level 
method, and getDirectReports() is the method name. 
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The level of the method is either instance, class, a collection 
of instances, or a collection of classes. 


Parameter definitions 
The definition depends on which command you are using: 
—  defineProcedure 


The method definition includes the definition of the 
parameters to the method. These must match the 
parameters as defined in the method signature in the 
class definition; that is, there must be the same number 
of parameters with the same names and types. Default 
values for parameters, which are included in the class 
definition, are not restated in the defineProcedure 
command. 


— addProcedure 


The method definition includes the definition of the 
parameters to the method. For each parameter, its type, 
name, and default value, if any, are specified. 


Language specification 

This defines whether the method body is written in C, C++, 
or pure ODQL. For example: 

language: "c++" 

or 

language: "odql" 

The default is C. 

Method description (addProcedure only) 


With addProcedure, a description of the method can be 
given as a character string up to 256 bytes long. 


In the case of defineProcedure, the description of the method 
is part of the class definition. 
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Method body 


This contains the code to be executed when the method is 
invoked. It contains a mixture of host language declarations 
and statements (C or C++) and ODQL declarations and 
statements, as described in Writing Methods with Embedded 
ODQL in the “Using Embedded ODQL” chapter. 


Two examples of a method definition are given below, one using 
defineProcedure and the other using addProcedure: 


defineProcedure Project Project::class:find(String n) 


{ 


}; 


language: "c" 


$defaultCF demoCF; 

$Bag<Project> p; 

$Project pr; 

$p = Project from Project where Project.name == n; 

$if (p.count() == 0) 

{ 
$p.delete(); /* collection clean up */ 
$return (NIL) ; 

hj 

$scan(p, pr) 

{ 


}; 
$p.delete(); /* collection clean up */ 
$return (pr); 


$break; 


addProcedure Location 


}; 


Location: :class:find(String n := "") 
language: "c" 
description: "Find a location given its name" 


$defaultCF demoCF; 

$Bag<Location> locs; 

$Location loc; 

$locs = Location from Location 
where Location.name == n; 

Sif (locs.count() == 0) 


{ 
$return (NIL) ; 
}; 


$scan(locs, loc) 


{ 
$return (loc); 


}; 
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Compiling a Method 


Before a method can be used, it must be compiled using the 
compileProcedure command. Note that compileProcedure 
compiles all the methods for a given class. Thus, the argument to 
compileProcedure is a sequence of class names, not method 


names. 


You can specify the following information when using the 
compileProcedure command: 


Class name 


The name of the class in which the methods to be compiled 
are defined. For example, to compile the methods in the 
Person class, you would type the following: 


compileProcedure demoCF: :Person; 


Options and arguments 


You can enter options and arguments as a character string 
following the class name. 


The following options and arguments are available: 


file name 


If a method calls a host language function that you want 
to be statically linked with the compiled method code, 
you can achieve this by including the .o file name of the 
compiled function here. For example, suppose the 
method distance() on class Location calls a C-language 
function called geoDist in module geo.c; geo.c is 
compiled into geo.o in the normal way. Then to compile 
the distance() method, linking in the geoDist function it 


calls, type: 


compileProcedure Location "geo.o"; 
Compiler options 


You can also specify options to be passed to the host 
language compiler, for example: 


compileProcedure Location "-H"; 
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-  -debug 


This argument prevents all temporary files created 
during compilation (such as .kc, .kcc, and .o files) from 
being deleted, so that the files can be used for debugging 
purposes. For example: 


compileProcedure Location "-debug"; 
—  -defaultCF class-family-name 


This argument can be used to define the default class 
family name to be assumed within the methods being 
compiled. This option overrides any defaultCF 
declaration given in the source of the methods. 


—  -envFile client-environment-file-name 


This argument specifies the name of the file to use in 
setting up the environment of the compileProcedure 
command. For more information on the format of this 
file and for the defaults used if the argument is omitted, 
refer to the Client environment file entry in the Reference 
guide. 


Remember that testing is not just about functionality; it is about 
availability, usability, performance, security, and potential for 
change. 


It is very convenient to use ODQL for testing—for example, for 
writing statements to invoke methods. 


Tip: If you plan to develop many versions or variants of 
your application, it is worth investing in creating re-usable 
(automated) test scripts. A useful technique is for these to 
start by restoring a database from a known backup or unload 
file; then the database is always in a known state at the start 
of the test. ODQL scripts will be adequate for most tests, 
although you could, if you wish, write a test application. 
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Error Handling in Methods 


Jasmine provides a set of macros to allow you to control what 
action should be taken when an error occurs: 


s ODB_PROCERROGOTO and 
ODB_PROCERRORGOTORESET 


= Other error handling facilities 


ODB_PROCERRGOTO and ODB_PROCERRGOTORESET 


The macro ODB_PROCERRGOTO can be used to specify that 
when an error occurs in the method, control should be 
transferred to a given label. This happens after the transaction 
has been rolled back. ODB_PROCERRGOTO is an executable 
statement which remains in effect until another 
ODB_PROCERRGOTO is executed or until 
ODB_PROCERRGOTORESET is executed. 


If there is no ODB_PROCERRGOTO in effect, execution 
continues with the statement after the error. If this was an 
assignment to a variable, the variable that was the subject of the 


assignment will have an error status which can be tested using 
ODB_ISERROR. 


An example of the use of ODB_PROCERRGOTO is given in the 
Reference guide. 
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Other Enor Handling Facilities 


Other error handling facilities include: 


« The ability to generate an error message for a user-defined 
error condition using the C API odbGenerateUserMtdError() 
function 


« The ability to test the error codes in ODB_CODE and 
ODB_DETAIL 


« The ability to test whether an ODQL assignment has failed 
using ODB_ISERROR and ODB_ERRORCODE 


Some of these are discussed further in the Macros in Embedded 
ODQLE section of the “Using Embedded ODQL” chapter. 
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10 Populating a Database 


In This Chapter 


This chapter explains how to load data into a database. It 
describes how to load small quantities of data, using the ODQL 
interpreter, and how to load larger quantities of data, using 
either the Jasmine load utility or your own load program. 


The flowchart below summarizes the tasks involved: 


Setting up a database 


Plan the database load 
operation 


Load the initial test data 


Hi 


Create a database for 
system testing 


Load the live database 


Modifying the structure of a database 
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Tip: You can load small quantities of multimedia and other 
data in Jasmine Studio by dragging the objects and dropping 
them into the database. See the Jasmine Studio online help 
for more information. 


Planning the Database Load Operation 


During your very early prototyping, you will probably be 
content to work with a database containing a very small number 
of objects, and you will not be too concerned with the actual data 
values. It is possible to set up such a test database very simply 
using interpreted ODQL. 


In the later stages of development, you will want to use a more 
substantial database for system testing for several reasons: 


= To test that your application works with the full variety of 
data conditions that might be encountered in live running 
(for example, NIL values for properties, long and zero-length 
character strings, and so on) 


= Toensure that the application gives adequate performance 
as the quantity of data increases 


= To show the application to users and test its usability with 
data that the users regard as realistic 


Finally, before the application goes live, there will in most cases 
be a take-on of live data from other systems. On rare occasions 
live running can start with an empty database, with the data 
building up as the application is used; in some other cases, there 
will be a data entry operation to capture data from manual 
records. However, in the vast majority of cases, the initial data 
will be loaded in a bulk operation from other systems. 


Three phases of data loading can then be distinguished—initial 
test data, system test data, and live data. These are discussed in 
the following sections. 
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Entering Data Using Interpreted ODQL 


You can use interpreted ODQL to enter data explicitly one object 
at a time, or you can do some simple test data generation. You 
will normally want to set up the ODQL in a file, so that you can 
regenerate the database whenever you wish rather than entering 
it interactively. 


Here is an example of how to generate data explicitly by entering 
it manually using a script. The example creates a Project, a 
Manager, and three Persons who will be assigned to that project: 
Project j; 


Manager m; 
Person p; 


j = Project.new ( name := "Christmas Party", 
staff := Bag{} ); 

m = Manager.new ( name := "Mother Brown", 
Manages = Bag{} ); 

m.address = "121 New Street, Newtown, Ontario, 
Canada"; 

MmM.manages = m.manages.add(j) ; 

j.manager = m; 

Pp = Person.new( name := "Sarah Brown" )j; 

j.staff = j.staff.add(p); 

p.address = "121 New Street, Newtown, Ontario, 
Canada", 

Pp = Person.new( name := "Jonathan Brown") ; 

j.staff = j.staff.add(p); 

p.address = "121 New Street, Newtown, Ontario, 
Canada"; 

Pp = Person.new( name := "Gertrude Smith") ; 

j.staff = j.staff.add(p) ; 

p.address = "59 Church Street, Newtown, Ontario, 
Canada"; 


Note how the properties of objects (properties or relationships) 
can be set either in the initial new() operation, which creates the 
object, or subsequently in an assignment. Note also how 
variables are used to identify objects when setting up 
relationships. 


Such a script can become quite lengthy if you try to create more 
than a handful of objects this way. Techniques for handling 
larger amounts of data are discussed in the subsequent sections. 
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Regenerating a Test Database 


However you generate your test data, you will want to save it so 
that you can readily recreate your standard test database. In the 
normal course of development and debugging, applications and 
methods will modify the data, sometimes incorrectly, so you 
want to be able to get it back quickly to its initial state. 


There are two approaches to this. One is to create a script for 
rebuilding the test database from scratch. This works well if you 
use ODQL to generate test data. 


The other approach is to unload the test database into an unload 
file, and reload from this unload file when you need to. You can 
achieve this using the unload and load utilities. These utilities 
give you a choice of unloading/reloading either the data or the 
metadata (class definitions) or both. 


This gives you more flexibility than using the backup and restore 
utilities, because it allows you to reload the test data even though 
the class definitions have evolved since the test data was 
unloaded. Restoring from a backup resets the classes and 
methods as well as the data instances, which could mean losing 
the results of your development work. 


To unload the data in your test database, use the unload 
command. This command takes a copy in unload format of the 
data and/or class information for a specified class or class 
family. For example, the following command unloads the data, 
including all classes and instances (but not the class definitions), 
from the class family projectCF into the file named unloadFile: 


unload -o unloadFile -c projectCF 


The unload file is a text file and can be edited with a text editor. 
The -c option causes the utility to include comments in the 
unload file. These are useful if you want to edit the unload file to 
modify the data or to add extra data before reloading it. 
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It is important to unload all linked data (that is, instances 
connected by relationships) in a single unload operation. The 
load utility will reinstate relationships between instances in a 
single unload file, but not across unload files. 


If you plan to specify the -n option in the load utility, you do not 
need to unload all linked data in a single unload operation. 
When the -n option is specified, instance numbers are not 
changed, and the load utility reinstates relationships between 
instances across unload files. 


To reload the test database, use the load command. This 
command loads information from an unload file into the 
database. To reload the test data, you should carry out the 
following steps. 


Either: 
1. Delete the store using deleteStore. 
Create a new store using createStore. 


2 
3. Create a new class family using createcf. 
4 


Reload the test data from the unload file using the load 
utility, as shown below. 


1. Delete all object instances from the store. 
If you have a top-level class ApplicationObject, you can do 
this in the ODQL interpreter by typing: 


Bag<ApplicationObject> aa; 
ApplicationObject a; 

aa = ao from ApplicationObject ao; 
scan ( aa, a) { a.delete(); }; 


2. Reload the test data from the unload file using the load 
utility, as shown below. 


The command to reload data instances from the unload file is: 


load unloadFile -d instance 
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The -d option ensures that you only load instances (neither class 
definitions nor class-level property values) from the unload file. 
The load utility will still work if some changes have been made 
to the class definitions since the unload file was made, subject to 
certain conditions. For example: 


« The classes and properties present in the unload file must 
still be defined, with compatible data types 


= There must be no new integrity checks that make the data 
invalid (for example, mandatory or unique constraints) 


Creating a Database for System Testing 


In many cases you may want to undertake system testing using a 
snapshot of live data. In this case, creating your system test 
database is exactly the same operation as creating your live 
database. 


There may be cases where the two situations are different. For 
example, you may want to test that your application can handle 
extreme conditions that are not guaranteed to occur in the live 
data. You may need to check that: 


= The application works up to its design limits in areas such as 
size of properties or number of elements in a 
collection-valued property 


= The application can handle NIL and empty values 
= The application behaves correctly in error situations 


« The application works in situations that will occur after a 
period of running (for example, handling a project that has 
come to an end) 


The design of such a system test database will often contain a 
mixture of real data and synthetic data. 


It is important to avoid over-relying on one single system test 
database. If it is critical that the application operates without 
error from the moment it goes live, you should use a variety of 
system test databases designed by different people. 
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A useful way of creating test databases is to generate unload files 
that can be loaded using the load utility. The format of unload 
files is defined fully in the Reference guide to allow you to achieve 
this. You might find that the simplest technique is to take an 
unload file produced from a simple test database, and use a text 
editor to add further test cases to the data. 


Loading the Live Database 


Loading a large database can be a very time-consuming 
operation and needs careful planning. This section discusses 
some of the possible strategies. 


In comparison with a relational database, loading in Jasmine is 
complicated by the need to set up relationships from one object 
to another. A relationship from A to B cannot be established 
until both A and B exist in the database. 


Although the presence of these direct relationships in Jasmine 
makes navigational access faster than it would be using relational 
joins, it imposes significant constraints on the order in which the 
steps of the load operation are carried out. The need to set up 
relationships does mean that database loading will be more 
complex and may take longer. 


There are three different ways you can load a Jasmine database: 


1. Write a program that reads the data from source files or 
external databases, and writes it directly to the Jasmine 
database using embedded ODQL. 


2. Write a program (or script) that reads the data from source 
files or external databases and outputs an unload file, which 
is then used as input to the Jasmine load utility. 


3. Write a program (or script) that generates a file of ODQL 
statements, which can then be executed through the 
interpreter. 
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In most cases, technique 2 (using the Jasmine load utility) will 
give the best performance and requires the least programming. 
In some cases, especially with very large quantities of data where 
you want to split the loading process into phases, it is best to 
load the bulk of the information using the load utility and then 
do some final “fixing-up” using a custom-written program or 
ODQL script. 


Use of the load utility has already been discussed in the section 
entitled Regenerating a Test Database earlier in this chapter. The 
following section gives advice and guidance on how best to use it 
when tackling very large database loading operations. 


Planning the Loading Process 


In planning the loading operation, there will be a number of 
objectives: 


=» To minimize the elapsed time for the loading operation 


= To build the database in such a way that runtime efficiency is 
optimized (for example, by ensuring that related objects are 
clustered together in storage) 


= Toensure that the process is recoverable 


It would be a major problem to have to start from scratch if a 
72-hour job fails after 71 hours because of the disk being full. 


= To audit or improve the quality of the supplied data 


In the sections that follow, various techniques for achieving these 
objectives are discussed. 
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Generating the Unload File 


Generating data instances in the right format for the unload file 
is usually straightforward. Many database packages include a 
utility to unload tables in comma-separated-value (CSV) format, 
and this will often be suitable for direct copying into the unload 
file, adding the relevant Jasmine information by concatenating 
files. 


Generating tags may require some thought. If the original data 
has a numeric primary key and the value is eight digits or less, 
you can use the primary key directly as the tag. Failing this, 
many relational databases provide a way of accessing internal 
tuple identifiers (or row identifiers) which are often numeric 
values in the right range. 


If neither of these techniques is possible, another approach is to 
modify the source database (or a copy of it) by adding an extra 
integer-valued column to the data and allocating a unique value 
to this column in a serial scan through the data. 


If the source data is in a relational database, you will generally 
determine the tags of related instances using a join query. For 
example, the relational database might contain a PERSON table 
with a column LOCATION holding the location name (a foreign 


key). 


In the Jasmine database, you want to replace the location name 
with a relationship to the location object, so you need to generate 
the tag of the relevant location in the unload file. Once you have 
established a column in the LOCATION table containing the tag 
(let us assume it is called LOCATION.TAG) you can typically 
extract the data with a sequence of SQL operations such as: 
CREATE VIEW PERSON_EXPORT AS 

SELECT PERSON.TAG, PERSON.NAME, ..., LOCATION.TAG 

FROM PERSON, LOCATION 


WHERE PERSON.LOCATION = LOCATION.NAME; 
UNLOAD PERSON_EXPORT INTO "filename"; 


The exact syntax depends on the relational database product you 
are using. 
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If the relationships in the Jasmine database do not correspond 
quite so closely to the foreign keys in the source data, you might 
want to use other techniques for generating tags or defer this 
part of the load operation. For example, if the target Jasmine 
database has a multi-valued relationship from Location to 
Person, as well as a single-valued relationship from Person to 
Location, you could: 


= Leave the inverse relationship unset during the initial load, 
and fix it up once the data is in the Jasmine database (see the 
topic Running a Multi-Phase Load for more information) 


= Performa second pass of processing on the unload file 
before loading it into the Jasmine database 


In this second pass, you generate a file of persons sorted into 
location order and use this to update each location record in 
the unload file with the tags of the persons at that location. 


=» Generate an unload file in which each location instance is 
immediately followed (or preceded) by the person instances 
at that location 


This is known as hierarchic loading, and can be done with 
multiple levels of relationship if you choose (for example, 
Persons within Departments within Organizations). Ina 
hierarchic unload you process persons one location at a time, 
generating tags for persons and locations as you go, so you 
only need to remember the person tags for one location at a 
time. 


With large quantities of data you need to try to make as many 
operations as possible serial. There are three essentially 
equivalent techniques for achieving this, and which one you use 
is largely a matter of personal preference: 


» Use SQL statements, views, and temporary tables to create 
tables in your relational database that closely match the 
structure of your target Jasmine database, and then unload 
these into CSV format to create the Jasmine unload file 


« Unload the relational tables into CSV format files, and then 
use operating system utilities to sort and merge these files 
into a format that corresponds to the target Jasmine structure 
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= Define Jasmine classes that correspond to the existing 
structure of your relational database 


Unload the relational tables into an unload file and then 
directly into these classes; then use ODQL to manipulate the 
data into the target design of your Jasmine database. 


How Many Load Phases? 


For a database of a few megabytes in size, you could consider 
loading it in a single operation. If a failure occurs, it would not 
be too difficult to start again from the beginning. 


For larger databases, you will probably want to split the loading 
process into a number of separate phases for the following 
reasons: 


=» Youcan checkpoint at the end of each phase (by taking a 
backup), so if a failure occurs you reduce the amount of 
rework 


« The larger the amount of data being loaded in one go, the 
greater the resources needed to fix up relationships 


This is equally true whether you write your own load 
program or use the Jasmine load utility. 


« Itis easier to monitor progress 


Running a Multi-Phase Load 


If you load the data in several phases, you will need to consider 
how to handle any relationships between instances loaded in 
different phases. If you are lucky, you will be able to organize 
the information into discrete, unrelated partitions with no 
relationships between one partition and another. More 
commonly, you will have to load the data leaving such 
relationships NIL for the time being, and then run a “fix-up” 
program to make the connections once all the loads are complete. 
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Clustering 


Such a fix-up program might take as input a file containing the 
relationship information in the form of primary keys (that is, 
unique-valued attributes). For example, if you need to fix up the 
relationships between Persons and Projects, the input file might 
contain on each line the name of a Person and the name of a 
Project on which the person works. 


A simple fix-up program for this example would simply do 
queries to find the relevant person and project, and then update 
either or both objects to refer to each other. 


With a very large database, this might take too long. In this case, 
a more sophisticated approach might be to scan all the projects 
and persons in the database, creating files relating the names of 
persons and projects to their object identifiers, and then use a 
sequence of sorts and merges to create a file containing the object 
identifiers of related persons and projects. This could then be 
processed to update the database directly without any queries, 
processing it in serial order of object-identifier, which is related 
to the physical sequence on disk. 


Generally speaking, data will be stored on disk in the order it is 
loaded. If two objects will often be accessed together (for 
example, two paragraphs in a single document) then it is a good 
idea to load them together; this maximizes the chance that they 
will be retrieved in a single disk transfer. 


This means that some presorting of data is often useful before 
you generate the unload file. For example: 


« If Persons will often be retrieved in alphabetical sequence, it 
is worth presorting them into alphabetical sequence before 
loading 


« If Persons will often be retrieved along with the projects they 
work for, it is worth presorting the data about Persons into 
project order so that Persons on the same project are stored 
near to each other 
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Writing Your Own Load Program 


If the data is post-processed after loading into the Jasmine 
database—for example, to initialize inverse relationships—this 
may change the size of an object, and this can result in objects 
being relocated to a new overflow area of disk where there is 
enough space. This will take longer and will negate the effect of 
any clustering. The simplest way to avoid this is to initialize the 
object when it is first created with dummy data that artificially 
increases its size; this can be removed during the post-processing 
phase. This can be done by adding trailing spaces to any String 
attribute. This also has the advantage of leaving space for any 
future expansion. 


Whiting Your Own Load Program 


If you choose to write your own loading program rather than 
using the Jasmine load utility, this will typically be implemented 
as aC or C++ application. 


If parts of the operation—for example, reading property values 
from a textual representation—are likely to be used frequently, it 
is worth writing them as Jasmine methods (typically, a class 
method on the class concerned). 


Assuming that the load operation will run as a single-threaded 
process with no concurrent activity on the machine, transactions 
can be longer than normal to reduce the need to flush buffers 
regularly to disk. 


To allow the load to be restarted in the event of a failure, it is a 
good idea to divide the input data into a manageable number of 
files and process one input file in each Jasmine transaction. In 
the event of a failure, it should then be possible to restart the 
load using all those files that remain unprocessed. One way of 
achieving this is to store the list of input files within the Jasmine 
database, deleting each file name in the transaction that 
processes it. Then on restart, the file names still present in the 
database will be precisely those that need to be processed. 
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Note: Some hints and tips to improve the performance of 
database loading are included in the “Performance Tuning” 
chapter. 
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In This Chapter 


This chapter explains how to change the structure of an existing 
database using ODQL. You can also make structural changes to 
a database using Jasmine Studio, as described in the Jasmine 
Studio online help. 


Specifying the checkLevel Environment Parameter 


Modifying the structure of the database can invalidate your 
existing methods. It can either make them invalid at the source 
level—for example, if you delete a class—or necessitate a 
recompilation. Jasmine makes optimization decisions at compile 
time which may need to change if the class definitions change. 


Jasmine will never recompile your methods automatically, but it 
can perform a check that tells you when this needs to be done. It 
is useful to do this checking during development, while the class 
definitions are subject to frequent change; during live operation 
when the database structure is stable, the checking is an 
unnecessary overhead and can be switched off. 
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Modesof Operation 


Many changes to the database structure can be made without 
any need for recompilation—for example, addition of properties 
and subclasses to existing classes. This means you can safely 
make these changes even though you did not develop the 
original classes yourself. Note in particular that the names of 
classes and properties are retained in the compiled object code, 
rather than being translated to internal numeric codes. 


The checkLevel parameter in the client environment file specifies 
whether a check should be made at the start of a session that the 
class definitions are still the same as when the methods were 
compiled. You can specify either of the following values: 


0 Nocheck is made. 


1 Immediately after the session starts, a check is made to 
ensure that no changes have been made to the definitions of 
classes that would invalidate the methods. If any of the 
checks fail, an error occurs, and the session terminates. The 
relevant methods should then be recompiled. 


Modes of Operation 


A Jasmine server can run in two modes: 
s Development mode 


In development mode, changes to the database structure can 
be made at any time. But there is a price for this flexibility, 
because every time a new transaction starts, the system 
needs to check whether any changes have been made that 
invalidate existing internal data structures. 


= Production mode 


In production mode, changes to the structure of the 
database—that is, the facilities described in this chapter—are 
prohibited. This gives a performance advantage because the 
system can avoid continually checking the validity of its 
internal tables. 


11-2 


Using J asmine 


Editing Classes 


As with the checkLevel environment parameter described 
earlier, it is best to use development mode while the class 
definitions are subject to frequent change and to use production 
mode during live operation when the database structure is 
stable. You change the run mode using the production_mode 
parameter of the Jasmine configuration utility. Refer to the 
“Configuring Jasmine” chapter of the Installation and Operations 
guide for more information. 


Editing Classes 


This section covers the following types of changes to a class: 
= Changing the class hierarchy 

=» Adding a new class to a class family 

= Creating a new class by copying 

= Deleting a class 


= Increasing the maximum size for instances of the class 


When you edit a class, the following happens: 
s The class definition, held within the database, is updated 


= If the updated class has instances, the instances are adjusted 
as necessary. For example, if a class is deleted, all the 
instances are deleted. 


Changing the Class Hierarchy 


You can add a subclass to an existing class at any time but can 
only add new superclasses or remove superclasses from an 
existing class if the class has not yet been built. 


If a class has already been built, you need to delete and redefine 
the class in order to change its superclasses. You can preserve 
data values by careful use of the unload and load utilities. Note, 
however, that the object identifiers of instances change after this 
process. 
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You can use the addSuper() method to define an additional 
superclass for an existing class. The target class and its new 
superclass must both belong to the same class family. For 
example, to add testCF::ClassA as an additional superclass of 
ClassB: 


ClassB.addSuper ("testCF", "ClassA") ; 


Adding a New Class to a Class Family 


You can add classes to existing class families in ODQL using the 
defineClass command or newClass() method. For further 
information on how to define new classes, refer to Defining the 
Classes in the "Setting up a Database” chapter. 


Creating a New Class by Copying 


Using ODQL 


You can create a new class by making a copy of an existing one, 
either by using ODQL or by using the unload and load utilities. 
Creating a new class by copying can be useful if you want to 
create a new version of a database without disturbing the 
existing version. For example, you might want class family 
demo97 to contain classes that are modified copies of those in 
class family demo96. 


You can use ODQL to create a new class by copying the 
definition for an existing class and then editing the copy: 


1. Use the print() method to print the class definition to a file. 
For example: 


Person.print (); 
2. Edit the output to produce the required new class definition. 


3. Use the execFile command from the ODQL interpreter to 
execute the ODQL statements in the file. For example: 


execFile Person.odql; 
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Note that this only copies the class definition. If you want to 
copy the methods as well, you can do so ina similar way. In this 
example, the current code of the Person::spendingLimit() method 
is printed to a file, where it can subsequently be edited: 


Person. getMethodSource (ISMETHOD, 
"spendingLimit") .print (); 


Using unload and load 


Deleting a Class 


You can use the unload utility to copy a class into an unload file, 
with or without its instances. You can then use the load utility to 
copy the class, with or without its instances, into a new class 
family. You can modify the class definition either by editing the 
unload file or by changing it after it is loaded into the new class 
family. 


You can delete a class using ODQL. 


When you delete a class, the following are also deleted: 
= Any subordinate classes of the deleted class 

= Any instances belonging to deleted classes 

s Any method libraries for the deleted classes 


Therefore, if you delete a class, you first need to be sure of the 
effect the deletion will have on the rest of the database. 


Jasmine does not automatically adjust any relationships from 
other classes to the deleted class. For example, if Person has a 
property of type Location, then if you delete the Location class, 
you should also delete this property. 


To delete a class, use the class-level delete() method. For 
example, to delete the Manager class you would specify: 


Manager .delete () ; 
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Increasing the Maximum Instance Size 


You can increase the maximum instance size of a class using 
ODQL, provided the Jasmine server is operating in development 
mode. 


When a class is defined, by default the maximum instance size is 
set to 4KB (which is also the minimum), although it can be set as 
large as 256KB. If you need to increase the maxInstanceSize of a 
class, you can do so using the setMaxInstanceSize() operation. 
The value you specify, which represents the number of kilobytes, 
will be rounded up to a power of 2. If checkLevel is turned on, 
you will need to recompile methods defined in this class after 
changing the maxInstanceSize value. 


Editing Property Definitions 


This section covers the following types of changes to property 
definitions: 


= Adding new properties to a class 
= Changing data types 


= Deleting properties from a class 


Adding New Properties to a Class 


You can add properties using ODQL. The new property will be 
immediately added to all instances of the class and of all its 
subordinate classes. 


Adding a property with a particular name may be disallowed if a 
subordinate class already has a property of that name with an 
incompatible definition, or if it inherits a property of that name 
via a different route. 
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You can add a property to a nominated class by using the 
addProperty() method. The property is automatically inherited 
by any subordinate classes. If the class already has any instances 
and the new property is an instance-level property, the new 
property is added to each instance. Its initial value will be NIL. 


The following example adds a new property salary of type 
Decimal [8, 2] to the class Person: 
Person.addProperty ( ISPROP, "salary", "systemCF", 


"Decimal", FALSE, FALSE, 
"The salary of the person", 8, 2 ); 


addProperty() includes a parameter allowing you to specify the 
maximum length of a String or ByteSequence property. For 
detailed information about the parameters of the addProperty() 
method, refer to the Reference guide. 


You can create or remove the uniqueness constraint for an 
existing property by using the method replaceUnique(). For 
example: 


Person. replaceUnique ("personnelNo", TRUE) ; 


Adding a uniqueness constraint will fail unless the existing 
values are unique. Since the error message will not help you 
directly in identifying the duplicates, it is best to check first that 
no duplicates exist so that they can be corrected. A useful way to 
do this is to use a group expression: 

Bag<[String pNo, Bag<Person> people]> gg; 

gg = group p in Person by ( p.personnelNo ) 


with (partition) ; 
gg = gg from gg where gg.people.count() > 1; 


The result of this is a collection of tuples. Each tuple contains a 
duplicated personnel number and a collection of Persons who 
share that personnel number. 


You can create or remove the mandatory constraint for an 
existing property by using the method replaceMandatory(). For 
example: 


Person. replaceManadatory ("personnelNo", TRUE) 
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Again, you cannot make a property mandatory if there are 
instances where it is currently NIL. You can check for existing 
NIL values using a simple query: 

Bag<Person> pp; 


pp = Person from Person 
where Person.personnelNo == NIL; 


You can change the default value of a property using the method 
replacePropDefault(). Note that changing the default will not 
affect any existing instances; it applies only to instances created 
after the new default is established. 


Changing Data Types 


Changing the definition of existing properties—for example, 
changing the type from Integer to String or changing the 
maximum length of a String—can be achieved only by creating a 
new property and deleting the old one. 


If there is existing data you want to preserve and convert, you 
can use the following sequence of steps: 


1. Add the new property with a new name, as explained in 
Adding New Properties to a Class earlier in this chapter. 


2. Useasimple script in the ODQL interpreter to set the value 
of the new property based on the value of the existing 
property. For example, if you were changing an Integer 
phoneNumber to a String newPhoneNumber, you could do 
this as follows: 

Bag<Person> pp; 
Person p; 
pp = Person from Person; 
scan ( pp, p) { 

p.newPhoneNumber = 
p.phoneNumber .convertToString () ; 
}; 

3. Delete the old property, as explained in the Deleting 
Properties section. 
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Changing Methods 


You must then decide whether you want to give the new 
property the same name as the one it replaces. To do this, you 
can go through the steps 1-3 above once again, except that in 
step 2 there is no conversion this time—just an assignment. 


Whether or not you do this, you will have to check any ODQL 
code in applications or methods that refers to the old property to 
verify that it remains valid. 


Another way to change the data type of a property is to unload 
the class using the unload utility, edit the unload file to change 
the property definition, and then reload the class using the load 
utility. Remember that unloading and reloading data will 
change the object identifiers. 


Deleting Properties 


You can delete a property using ODQL. 


When you delete a property, it is deleted from all instances of the 
class and from all subordinate classes that inherited it. 


You will have to change any applications or methods that refer to 
the deleted property. 


To delete a property, use the removeProperty() method. 


For example, the following code deletes the eMail property from 
the class Person and all its subordinate classes: 


Person.removeProperty( ISPROP, "eMail" ); 


Changing Methods 


This section covers the following types of changes to methods: 
=» Adding anew method to a class 


= Changing the specification of a method in the class definition 
(for example, adding an extra parameter) 
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= Changing the code of a method 
= Deleting a method 


If a method is currently inherited from a superclass, you may 
want to refine it, for example, to use a different implementation. 
This is exactly the same as adding a new method. 


Adding a New Method 


You can add a new method using ODQL. 


You can add a new method "on the fly" by using the command 
addProcedure. This is similar to the command defineProcedure. 
For example: 


addProcedure Void Hardware: :instance:printDetails () 
{ 

/* declare ODQL variables */ 

$String hardname; 

$Integer hardprice; 

/* obtain hardware name, and price */ 

Shardname = self.name; 

$Shardprice = self.price(); 


/* display hardware name */ 

$String.format ("Hardware name = %s\n", 
hardname) .print () ; 

$String.format ("Hardware price = %d\n", 
hardprice) .print(); 


$return; 


}; 


Changing the Specification of a Method 


To change the specification of a method as it appears in the class 
definition—for example, to add or remove parameters, or change 
the type of a parameter—you must create a new method with the 
same name. 

You can replace a method in ODQL in the following way: 

1. Delete the old method using removeMethod(). 


2. Define anew method using addProcedure. 
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Changing Methods 


You can use ODQL to change the code of a method in the 


following way: 


1. Use the defineProcedure command to define the revised 


code for the method. 


2. Use the compileProcedure command to compile the new 


code. 


Removing Methods from a Class 


You can remove a method from a class by using the method 


removeMethod(). For example: 
Hardware.print (); 


> defineClass testCF: :Hardware 
super: Composite 
{ 
maxInstanceSize: 4; 
instance: 
String name; 
Void printName () ; 
Integer price (); 
}; 
Hardware .removeMethod (ISMETHOD, 


Hardware .print () ; 


> defineClass testCF: :Hardware 
super: Composite 
{ 
maxInstanceSize: 4; 
instance: 
String name; 
Integer price (); 


}; 


"printName") ; 


You can execute this method both before and after building the 
target class. However, you cannot use this method to delete 


methods inherited from a superclass. 
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12 Performance Tuning 


In This Chapter 


Responsibility for achieving performance goals is inevitably 
shared between the application and database developer, on the 
one hand, and the operational service provider on the other. The 
service provider can only work within the constraints of the 
application as designed and written, so the primary 
responsibility falls on the developer. This chapter describes 
some of the factors that the developer should take into account to 
ensure that performance requirements are met. 


Key Performance Considerations 


Performance is measured by throughput, response time, and 
resource costs. 


To establish throughput requirements, you need an 
understanding of the total workload—both routine batch and 
online processing and ad hoc requests. 


To establish response time requirements you need to understand 
the users’ tasks and the effect of response time on users’ 
efficiency, effectiveness, and job satisfaction. 
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Key Performance Considerations 


Resource costs include both hardware and people. There is a 
cut-off point where using more personal time and effort to 
reduce hardware requirements is a false economy. In the early 
stages, however, a small amount of effort will probably give 
large resource savings. 


Generally speaking, performance tuning is a two-stage process: 


1. Reduce the resources (disk transfers and CPU time) used by 
individual transactions. 


2. Examine concurrency effects to reduce queuing delays, for 
example, by using shorter transactions or eliminating hot 
spots. 


The first coarse performance improvements can be made without 
any detailed measurement or control being in place: the effects 
will be obvious. Later, as more detailed adjustments are made, it 
will be important to establish a systematic process for making 
and recording performance measurements to verify that any 
changes have the desired effect. If you make changes to the 
system for performance reasons, make measurements in 
controlled conditions before and after so you can evaluate the 
effect of the change, change only one thing at a time, and keep a 
detailed record of the changes made and the effect on measured 
performance. 


Designing for Performance 


Ideally you should take performance into account at every stage 
of the design and planning process—from initial requirements 
capture through scaling up for live running: 


= During the development phase, start by understanding user 
tasks, time constraints, and workload. 


Bear these in mind as you develop successive prototypes, 
and never show the user functionality that you do not know 
how to scale up to the target volumes. Use successively 
larger volumes of data in successive prototypes, and 
introduce steadily increasing numbers of concurrent users. 


12-2 


Using J asmine 


Key Performance Considerations 


= Users forced to make a choice will often accept reduced 
functionality in return for improved performance. 


The specification is not sacrosanct. 


« Minimize the risk of user dissatisfaction by increasing the 
number of users slowly rather than all at once. 


# Donot worry about tuning the system environment until 
you are reasonably sure that you cannot make further 
improvements to the design of the database and application. 


Problem Investigation Methods 


Prevention is better than cure, but for many projects that operate 
in a prototyping style, the reality is that performance receives 
attention only when it is found to be a problem. 


The illustration below shows a typical sequence for investigating 
problems: 


Y 


Investigate the 


application design 


i 


Investigate the 
database design 


wa 


Investigate the 
environment 


Identify design changes |} 
(application/database) 


The key point here is to ensure that the application design and 
the database design are right before you start looking at the 
environment, that is, the configuration of the hardware, 
operating system, and memory. 
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The main areas you need to cover during your investigation are: 
« Isolating the queries causing trouble 
= Understanding the database access paths involved 


= Deciding whether the problem is a single-user or a 
multi-user problem 


For a multi-user problem, you should look at transactions 
and database locking. 


Performance Checklist 


This section provides a checklist of points for you to consider 
when you are designing and implementing a Jasmine database or 
application. 


Application Design 


« Minimize the amount of data and the number of requests 
passing between the client application and the database 
server (for example, by making the conditions in the where 
clause of a query as selective as possible) 


=» Do not put information on the screen unless you are 
reasonably sure the user wants it 


If you are not sure, provide it only when the user explicitly 
requests it. 


» Avoid invoking methods within the where clause of a query 
if the number of candidate objects is large 


However, do this in preference to retrieving all the objects 
and then applying the method to each one individually. 


« Use relationships and avoid relational-style joins 


Generally, avoid having more than one class or collection in 
the target list of a query. 
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If you use relationships in a query, think carefully about 
which object to start from 


Choose the one that touches fewer objects. For example, to 
get the names of employees located in Perth, you can write 
any of the following queries: 


Example 1: 
pnames = Person.name from Person 

where Person.location.name == "Perth"; 
Example 2: 


loc = Location. find("Perth") ; 
pp = loc.persons; 
pnames = pp.name from pp; 


Example 3: 

loc = Location from Location where Location.name = 

"Perth"; 

pnames = Person.name from Person where 
Person.location == loc; 

Example 4: 


pnames = P.name from Person P, Location L 

where P.location == L and L.name == "Perth"; 
The relative speed of these queries depends on the sizes of 
the two classes, on the indexes that are present, and on how 
the relationship is implemented. It also depends on how the 
Jasmine optimizer decides to execute each of these queries. 
The only way to be sure you have written the query in the 
best possible way is to try all these possibilities and measure 
them. However, you can make an informed guess by 
considering how many objects each query has to touch, 
assuming the optimizer has perfect knowledge. 


In the code of methods, use C or C++ for any complex 
manipulation of numeric or string values in preference to 
ODQL 


Avoid using collection variables with thousands of elements 
It is often possible to avoid this by doing a scan instead. 


If you need to add elements to a collection-valued property, 
use the construct: 


Person.directAdd( "skills", "French" ); 
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rather than: 
Person.skills = Person.skills.add("French") ; 


This can be especially valuable if the collection is large or the 
construct is used in a loop, as it saves creating large 
collections in the work store. 


If you use add() or remove() to modify collection-valued 
variables in a loop, use delete() to clear the unwanted values 
from the work store. For example: 
Bag<Integer> ii, oldii; 
Integer i; 
i=1; 
ii = Bag{}; 
while ( i< 10000) { 

oldii = ii; 

ii = ii.add(i); 

i=idt¢i; 

oldii.delete(); 
}; 
An even better solution might be to create a dummy object 
with the collection as a property, then use directAdd() to 
build up its value. 


Avoid retrieving large multimedia objects into application 
memory 


Instead, write a method that processes the object in the way 
you want (for example, copying it to a file on the client 
machine). 


Any frequently executed operation that accesses several 
database objects should probably be a method 


If you only need a person’s name, retrieve pp = Person.name 
from Person 


Do not retrieve pp=Person from Person and then request 
pp-name, because this may create the need to go back to the 
server to get it. 


Avoid any changes to metadata during normal operation of 
the application, and ensure that during normal operation 
you run in production mode 


This means the system does not have to check continually 
whether the metadata has changed. 
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Performance Checklist 


Ensure that the checkLevel parameter is turned off (that is, 
set to zero) in the client environment file 


This avoids the overhead of checking whether the classes 
have changed since the methods were last compiled. 


Use indexes on attributes that often appear in where clauses 
or that are defined to be unique 


Consider carefully how to implement relationships 


Various alternative implementations are described in 
Defining the Relationships in the “Designing a Database” 
chapter. The choice can have a significant impact on 
performance. 


Define operations to hide the way you have implemented the 
relationship, especially for update 


This, too, is discussed in the Defining the Relationships 
section in the “Designing a Database” chapter. If 
applications manipulate relationships via operations, you 
have more scope to experiment with different 
implementations. 


Avoid over-normalization (for example, by use of 
collection-valued attributes) 


Avoid making the class hierarchy unnecessarily deep 


Only define a subclass with good reason, for example, to 
exploit polymorphism; the same effect can often be achieved 
with attributes and NIL values. You should rarely need 
more than three levels of user-defined classes. Avoid 
multiple inheritance unless you have a very good reason. 


Generally avoid introducing entities (objects with OIDs) 
where literals would do 


Keep all the information about one business object within 
one object if you can. 
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Multimedia 


A critical issue in many applications is the response time delay 
caused when transferring large multimedia objects between the 
server and a client machine. This can sometimes be reduced by 
caching the data on the client machine. For example, you can use 
timestamps or checksums to check whether the version currently 
held on the client is up to date. Other techniques to reduce this 
problem include: 


= Increasing the network speed or bandwidth 


= Holding replicated copies of the entire collection of 
multimedia objects on local servers so that they are always 
retrieved over a fast local area network 


= Holding compressed images in the server and 
decompressing them at the workstation 


= Maintaining the information at a reduced resolution or at 
several different resolutions 


= Changing the user interface design so that images are only 
presented on request and so that the user gets feedback on 
progress while the transfer is under way 


Database Loading 


« Itis advisable to use the load utility to carry out database 
loading rather than writing out your own load program. 


« Think how best to fix up the references from one object to 
another so that performance scales up linearly with database 
size. Watch out for nested loops; they can often be replaced 
by a sort/merge sequence. 


= Try to load the data so objects that will be retrieved together 
are loaded together. 


« Try to load objects with a size sufficient to ensure they will 
not subsequently expand and overflow. If necessary, include 
dummy data in each object to reserve space for expansion. 
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Performance Checklist 


Load the data without Jasmine indexes and then build the 
indexes later, unless you need to do queries within the 
loading process. Take advantage of the compact option of 
the listIndex() command to rebuild a primary index. 


Remove all constraint checking during the load process, 
especially the unique constraint. This can be achieved by 
invoking replaceUnique(FALSE) before the load and 
replaceUnique(TRUE) after the load. 


Jasmine uses a classical transaction and locking model. 
Information about its locking technique is provided in “The 
System Environment” chapter of the Installation and Operations 
guide. 


Where transactions do no updates, define them as read-only 
transactions in the Transaction.start() method. 


This reduces the amount of locking needed. 


Keep transactions short to minimize the number of locks 
held. 


Try to avoid holding transactions open during the user’s 
thinking time. Instead, close the transaction as soon as the 
data has been read and be prepared to re-read the data 
subsequently, if necessary. If you need to protect against the 
object changing in the meantime, consider time-stamping the 
object and checking in the application that the timestamp is 
unchanged. 


On the other hand, if contention is not a problem, longer 
transactions might be useful, because there is a certain 
overhead in closing one transaction and starting a new one. 
The overhead of starting a new transaction is particularly 
noticeable when running in development mode, because the 
system can no longer assume that its cached metadata is 
up-to-date. 


Try to avoid having singular objects in the database accessed 
by every transaction (for example, an object containing the 
current tax rates). 
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Deadlocks 


Such objects can act as hot spots, effectively limiting the 
maximum concurrency to one. Class-level properties can 
also cause this problem. If you do have such a hot spot, load 
the data into application memory on first connecting to the 
database. 


Avoid accessing metadata (for example, class definitions) 
within transactions that are executed frequently. 


This too can result in hot spots. 


Contention can be very high when you run with a small 
database, because each lock is then locking a large 
proportion of the database. 


Try to scale up the database size to realistic levels before you 
scale up the concurrency. This will also reveal situations 
where indexes are needed to prevent a query doing a serial 
scan. 


Contention problems will often manifest themselves through a 
high frequency of deadlocks. One way to reduce the number of 
deadlocks is simply to reduce the amount of contention, as 
discussed in the previous section. However, there are other 
actions that can be taken: 


Ensure that the method is written so that it recovers from 
deadlock. 


The way to do this is to use ODB_PROCERRGOTO to 
transfer control to an error label. At this label, check the 
error code to see if deadlock has occurred and, if so, restart 
processing so that the transaction is re-tried. 


Try to avoid writing transactions that read a large amount of 
data and then do an update. 
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Performance Checklist 


If two such transactions run concurrently, they will both 
succeed in reading all the data they need, and one of them 
will then fail with a deadlock on attempting to upgrade the 
read (shared) lock to an update (exclusive) lock. It would be 
better to obtain the update lock earlier: this is likely to cause 
the transaction to wait, if necessary, rather than failing with 
deadlock. 


To separate data over the disks on the machine, create 
multiple stores or stores that span multiple disks. 


Each concurrent application program requires a dedicated 
process. 


If these client processes all run on the server machine, the 
memory requirement will increase with the number of 
concurrent connections. One solution is to run the client 
process on a separate machine, but this can reduce response 
time if many pages have to be transferred. Another solution 
is to implement an application server, perhaps under the 
control of a transaction processing monitor, in such a way as 
to remove the need for one Jasmine client process for each 
concurrent user. 
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Access (to the database) 

An action that causes data to be retrieved 
from the database or that causes the database 
to be updated. 


Application 

An application has three parts: the 
presentation component, the business 
process component, and the data 
management component. In the context of a 
database system, the term application is 
generally used to refer to the entire system, 
including the database and the user-written 
programs accessing it. For the more 
restricted meaning of a particular program 
accessing the database, the term application 
program is used. 


Application developer 
See Developer. 


Application program 

An application program is a user-written 
program that makes requests on a database. 
It is one part of the application as a whole. 
Methods running under the control of 
Jasmine are not considered part of the 
application program. 


Application user 
The end user of an application. 


Archive 

The process of taking a backup, either of an 
entire database or of the database journal. 
Archive is also used to refer to the tape or 
other medium on which the backup is 
written. See also Journal. 


Argument 

Operating system commands have 
arguments but ODQL operations and 
methods have parameters. See also 
Parameter, System commands. 


Attribute 

A property whose value is a literal, for 
example, color or age. This term can be used 
both at class- and instance-level, depending 
on the context. See also Level, Property, 
Relationship. 


Availability 

A measure of whether an information 
system is available to its users when 
required. 


Characteristic 
A property or method. See also Method, 
Property. 
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Class 

A collection of objects with common 
features. A class can be either of the 
following: 


=» Asystem-defined class supplied with 
Jasmine to cover the basic types of objects 
needed 

=» Auser-defined class created by the user 
or a third party with a defineClass command 


All objects (literals and entities) belong to a 
class. Classes are organized into hierarchies 
(See Class hierarchy). 


Class-collection-level 
See Level. 


Class family 

A named collection of related classes. 
Different class families can be independently 
developed and can be reused in different 
applications. A system class family, a 
multimedia class family, and several others 
are supplied with Jasmine. 


Class hierarchy 

Classes are organized into hierarchies that 
represent the natural relationships of 
specialization and generalization. The 
hierarchy becomes more specific the lower 
down you go. 


Any classes above a given class are its 
superior classes and any classes below are its 
subordinate classes. A class immediately 
above a given class is its immediate 
superclass and any class immediately below 
the given class is its immediate subclass. See 
also Subclass, Superclass. 


Class-identifier 

A class-identifier is used to identify a class 
uniquely. An example of a class-identifier is 
projectCF::Person. 
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Class-level 
See Level. 


Client application 

An application program that issues requests 
from a client to a Jasmine database. In 
Jasmine, client applications can be 
developed using a variety of tools, including 
JADE and the C API. 


Client environment file 

A text file that defines the environment in 
which a Jasmine session operates. This file 
specifies the settings for a range of system 
features that control the session. 


The file contains a series of client 
environment parameters which specify 
details such as the size of the input-output 
buffer to be used, the name of the directory 
in which log files are to be created, and the 
level of system diagnostics required. 


See also Environment variables. 


Client platform 
The computer system on which the client 
application runs. 


Client process 
The process within the Jasmine system that 
executes on behalf of a single user session. 


Client/server model 

A model of computing in which 
functionality is divided between a 
component that makes requests (the client) 
and a component that responds to them (the 
server). The client and server are typically 
situated on different computers, although 
this is not a requirement of Jasmine. 


Entity 


Collection 

An assortment of objects of the same type, 
such as a collection of numbers or a 
collection of people. There are several kinds 
of collections, such as arrays, bags, lists, and 
sets. The kind of collection determines its 
properties, such as if the collection is 
ordered and if duplicates are allowed. See 
also Single. 


Collection-valued 

A property, method, or variable whose value 
is a collection. Sometimes referred to as 
multi-valued. See also Single-valued. 


Constraint mode 

Constraint mode applies to transactions. 
When constraint mode is set, changes to the 
database structure are not committed until 
the end of a transaction, rather than being 
committed immediately. This gives you the 
opportunity to cancel or refine structural 
changes before they are committed to the 
database. 


Database 
This term is used to mean a system store and 
all the stores it references. See also Store. 


Design specification 

A detailed specification that, in addition to 
the entities, relationships, and operations 
identified in the analysis phase, specifies the 
algorithms and supporting classes for the 
implementation. See also Requirements 
analysis. 


Developer 
Someone who is responsible for: 


= Analyzing user and enterprise 
requirements 

= Designing and implementing a Jasmine 
database and application to meet those 
requirements 

= Validating that the database and 
application meet the requirements 

= Handing the database and application 
over to the system administrator for 
installation 


See also System administrator. 


Dynamic ODQL 
See ODQL. 


Element 

One of the components of a collection. The 
elements of the collection {1,2,3} are the 
integers one, two, and three. 


Embedded ODQGL 
See ODQL. 


Encapsulation 

The ability to define an interface to an object 
without revealing the implementation. This 
allows the implementation to change 
subsequently. 


Entity 

An entity has a fixed lifetime that starts 
when it is created and ends when it is 
deleted. It typically represents an external 
real-world object and has attributes whose 
values can change at any time. 
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Entity-relationship model 

A diagram showing the types of 
relationships between objects, for example 
whether relationships are one-to-one, one-to- 
many, or many-to-many. 


Environment variables 

Environment variables provide Jasmine with 
details about various aspects of the 
environment in which it is operating. 
Jasmine uses the following types of 
environment variables: 


= Operating system environment variables 
= Jasmine environment variables 


Jasmine environment variables are active 
only when you are using Jasmine, whereas 
operating system environment variables are 
active before, during, and after Jasmine is 
invoked and can be used by other 
applications. Environment variables should 
not be confused with environment 
parameters, which are defined in the 
Jasmine client environment and other 
configuration files. 


See also Client environment file. 


Extent 

Each store is made up of one or more 
extents. The first extent is created when the 
store is created, and more extents can be 
added to increase the capacity of a store. 
Each extent is associated with one or more 
files. Extents made up of multiple files are 
said to be striped. See also Store. 
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Host language 

ODQL is rarely used to write an entire 
application. Instead, a separate host 
language such as C or C++ is used to write 
the business logic of the application, 
accessing data from the server using ODQL 
statements. A host language can also be 
used to write methods associated with 
database objects. See also Application. 


HTML file 

An file that is written (formatted) in the 
Hypertext Markup Language and can be 
viewed as a World Wide Web page. 


Identifier 
See Object identifier. 


Immediate subclass 
See Subclass, Superclass. 


Immediate superclass 
See Subclass, Superclass. 


Inheritance 

A mechanism for creating a new class 
definition by refining existing class 
definitions. Inheritance is the mechanism by 
which a subclass exhibits the behavior 
(operations and properties) defined for its 
superclass, as well as any additional specific 
behavior of its own. 


Jasmine supports multiple inheritance, 
which means that a subclass can inherit 
attributes and operations from more than 
one superclass. 


Multimedia 


Instance 

The term instance is used to describe the 
relationship between an object and its class, 
for example, "A is an instance of B." The 
term is sometimes used loosely as a 
synonym for object to emphasize that the 
individual object rather than the class is 
being discussed. If A is an instance of B then 
it is also an instance of all superclasses of B. 
If you want to talk of the specific class that A 
belongs to, you can say "A is an immediate 
instance of B." See also Object. 


Instance-collection-level 
See Level. 


Instance-level 
See Level. 


Interpreted ODQL 
See ODQL. 


Journal 

A collection of files used to record database 
activity. The journal, if used, becomes the 
unit of backup and restore, allowing 
incremental backups to be taken instead of 
backing up the entire database each time. 
See also Archive. 


Level 

The level of a property or method 
distinguishes whether the property or 
method applies to instances, classes, or 
collections. There are two levels for 
properties: class-level and instance-level. 
There are four levels for methods: instance- 
level, class-level, instance-collection-level, 
and class-collection-level. 


Literal 

A literal is a value, for example, an integer or 
a string. Literals are objects, but they do not 
have object identifiers; they exist in the 
database only as the values of attributes of 
entities. 


Metadata 
Information defining a class in a database, 
including class properties and methods. 


Method 

The term method is used to mean both an 
operation and its implementation. In 
contexts where extra clarity is required the 
term operation is used to mean the interface 
visible to other objects, while the term 
method is used to mean the internal 
implementation. An example is the phrase 
“two different classes might supply different 
methods to implement the same operation.” 


Methods are executed on the server. There 
are four levels for methods: instance-level, 
class-level, instance-collection-level, and 
class-collection-level. A method consists of 
two parts: the specification and the body. 
The specification defines the method's name, 
the names and types of its parameters, and 
the type of its result. The body is the code 
used to implement the method. The code 
can be written using embedded ODQL in C 
or C++ or using the C API. See also Level, 
ODQL, Operation. 


Multimedia 

Information in the form of images, text, and 
sound and various other types of media. 
Strictly speaking, this term should be 
applied to information that uses a number of 
these media in combination. 
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Multiple inheritance 

The mechanism that allows a class to inherit 
from more than one immediate parent. See 
also Inheritance. 


Multi-valued 
See Collection-valued. 


Normalization 

A relational database term referring to a 
process where each value in a relation is 
non-decomposable as far as the system is 
concerned or, to put it another way, when 
only one value (not a collection of values) 
occupies one row and column position and 
are referenced through indexes, primary 
keys, and foreign keys to avoid non- 
duplication of data. Although this term is 
not an object database term, the concept is 
helpful when deciding whether to use 
collection-valued attributes or classes and 
subclasses in your object database design. 


Object 

A thing with its own identity, state, and 
behavior. The term sometimes refers to an 
object outside the computer system, 
sometimes to a computer representation of 
an external object, and sometimes to an 
object that is purely internal to the computer 
system. In the context of Jasmine, an object 
is either a literal value such as the number 
93.7, or a uniquely-identifiable entity in the 
database, often representing an external 
object or event such as a person or a project 
milestone. The class Object is the top of the 
Jasmine class hierarchy, and thus includes 
entities and literals. See also Instance. 


Glossary-6 Using Jasmine 


Object base 
See Store. 


Object database 

This term is used generically in the sense of 
object database technology, which allows a 
shared pool of information to be maintained 
in the form of objects. 


Object identifier 

An object identifier (OID) is the internal 
quantity used to identify entities in a 
database. Each object identifier is unique 
and permanent. The object identifier in 
Jasmine is a logical identifier, not a physical 
address. 


Object technology 

Disciplines for modeling and developing 
software that make it easy to construct 
complex systems out of individual 
components. The fundamental concepts of 
object technology include abstract data 
typing, inheritance, and object identity. 
These concepts provide a framework 
whereby programmers can easily model, 
prototype, and implement real-world 
applications. 


ODQL 

The language provided by Jasmine for 
database programming. ODQL statements 
can be any of the following: 


= Embedded ODQL 

Embedded and compiled in the host 
language. 

s Dynamic ODQL 

Constructed and issued by an application at 
runtime. 

a Interpreted ODQL 

Typed by a user or input from a file. 

= CAPI 

Executed from an application written using 
the C API via the odbExecODQL() function. 


Reference 


ODQL interpreter 

The interpretive environment for executing 
ODQL statements and commands entered 
from the terminal or from a file. 


ODQL preprocessor 

The software which translates ODQL 
statements embedded in a host language, 
such as C or C++, into a program written 
entirely in the host language. The program 
is then compiled. 


OID 
See Object identifier. 


Operation 

Roughly synonymous with method but used 
to emphasize the function (what is done) 
rather than the implementation (how it is 
done). See also Method. 


Parameter 

ODQL operations and methods have 
parameters. The parameters in the method 
definition are formal parameters, those in 
the invocation are actual parameters. 


Entries in the client environment file are 
referred to as environment parameters. 


See also Argument, Client environment file. 


Performance 

The performance of an information system is 
measured by its throughput and response 
time (See Response time, Throughput). 


Polymorphism 

An operation is said to be polymorphic if it 
can be implemented in different ways 
depending on the class of object to which it 
is applied. Polymorphism simplifies 
application development because the user 
does not have to check the type of an object 
before invoking an operation. It also allows 
a new object type to be introduced without 
affecting existing programs. 


Potential for change 

The degree to which an information system 
is capable of evolving to meet changed 
requirements and to incorporate new 
technology. 


Property 

A value associated with an object. A 
property can be either an attribute or a 
relationship and can be used both at class- 
and instance-level, depending on the 
context. See also Attribute, Level, 
Relationship. 


Query 

A syntactic construct that retrieves elements 
of a collection satisfying a given condition. 
This is not the same as a request (See 
Request). 


Reference 
See Relationship, Value. 
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Refinement 

The process of modifying the characteristics 
of methods and properties that a subclass 
automatically inherits from its superclasses. 
Use refinement when you need to: 


= Supply a different method for an 
operation (for example, the procedure for 
calculating annual leave entitlement for 
managers might be different from that for 
other employees) 

= Change some aspect of a property 
definition (for example, the default value of 
the property) 

= Specify more rigid constraints on classes 
that are lower in the class hierarchy (for 
example, the attribute 
professionalQualifications might be 
mandatory for managers but optional for 
other employees) 

= Establish a new definition because there 
is an inheritance ambiguity (See also Multiple 
inheritance) 

= Inthe case of class properties, to specify 
that the subclass does not share the value of 
the property with its superclass 


Relationship 

A property whose value is an entity, 
represented by an object identifier (See 
Object identifier). This term can be used 
both at class- and instance-level, depending 
on the context. Where a relationship exists 
we can say that one object references 
another. 


The term can also be used to describe a pair 
of relationships in which one is the inverse 
of the other. See also Attribute, Level, 
Property. 


Request 

An invocation of an operation, which results 
in execution of a method or access to a 
property. The object to which the request is 
directed is called the target of the request. 
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Requirements analysis 

The detailed specification of a problem, 
identifying the entities or classes and the 
relationships between the entities and 
operations performed for the application or 
product. 


Response time 

The elapsed time, measured by the user of a 
system, for the system to respond to 
requests. See also Performance. 


Run mode 

The run mode specifies the sort of service 
that Jasmine is running. This can be either a 
development session, which allows you to 
make changes to metadata at any time, or a 
production session, which prohibits changes 
to metadata. 


Security 

The measure of protection a system provides 
against unauthorized attempts to access 
information and services, or to interfere in 
its operation. 


System administrator 


Server 
The Jasmine server process that performs 
two main functions: 


= Allowing clients to connect so that 
application sessions can start and finish 

= Performing low-level data management 
functions on behalf of clients, for example 
locking and transaction management 


Higher-level data management functions are 
performed in a process called the agent 
process: one agent process is started on 
behalf of each concurrent client. 


When discussing client/server architecture, 
the Jasmine server process and agent 
processes are collectively referred to as the 
database server. 


Service provider 

A collective term for individuals concerned 
with the day-to-day management of 
information systems, with user training and 
support, and with planning the way the 
information system will evolve. 


Single 
Something that is not a collection. See also 
Collection. 


Single-valued 

A property, method, or variable whose value 
is not a collection. See also Collection- 
valued. 


SQL 

Originally Structured Query Language: a 
standard language for accessing relational 
databases. 


Store 

The physical container for Jasmine objects. 
A store is made up of one or more extents, 
each of which is associated with one or more 
files. Extents made up of multiple files are 
said to be striped. See also Extent. 


Subclass, superclass 

The superclasses of a class are those classes 
explicitly listed under super: in its class 
definition. The term immediate superclasses is 
used to emphasize this. 


The classes superior to a class are its 
immediate superclasses, their immediate 
superclasses, and so on. This is used in 
phrases such as "A must be an instance of B 
or of a class superior to B." 


The subclasses of S (or immediate subclasses, for 
emphasis) are the classes of which S is an 
immediate superclass. A class is said to be 
subordinate to S if it is a subclass of S, or a 
subclass of a subclass of S, and so on. 


System administrator 

Someone who manages a Jasmine system, 
performing the role of service provider. The 
system administrator’s responsibilities 
include: 


= Resource and capacity planning 

= Assembly of the various components, 
including an issued application, the Jasmine 
issued software, the platform and network 
on which it runs, and filestore resources 

=» Day-to-day management of 
performance and availability 

s Monitoring of service levels 


The system administrator may or may not be 
the same person as the manager of the 
platform itself, depending on the scope of 
the Jasmine system. 
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System commands 

Jasmine provides a number of commands 
that can be invoked from the operating 
system. These commands are used to 
perform operations such as creating or 
deleting a store or class family. 


Throughput 

A measure of the amount of work a system 
can perform in a given time. See also 
Performance. 


Top-level class 

A class that inherits directly from Composite 
is sometimes called a top-level class. There 
must be at least one top-level class in a class 
family, but there can be several. 


Transaction 

A discrete activity performed on a database. 
Transactions in Jasmine follow the classical 
behavior of transactions in other database 
systems: they are atomic, consistent, isolated, 
and durable: 


= Atomic: a transaction is the smallest unit 
of recovery. 

= Consistent: a transaction takes the 
database from one consistent state to another 
consistent state. 

« Isolated: during its execution, a 
transaction cannot see any changes made 
concurrently by other transactions. 

= Durable: once a transaction commits, the 
system will ensure that its effects persist in 
the database even if subsequent failures 
occur. 


These are sometimes referred to as the ACID 
properties. 
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Tuple 

Composite values containing a number of 
components. These components can be 
atomic literals or entities, collections of 
literals, collections of entities, user-defined 
classes, or collections of user-defined classes 
(but not tuples). Tuples are used to retrieve 
and process structured results from queries, 
group-expressions, and certain system 
methods. 


Type 

This term is used in the context of the ODQL 
language when talking of the types of 
variables or of syntactic constructs. For 
example, a variable of type employee takes a 
value of class employee. The term is also 
used when referring to the type of an 
attribute, for example age has type integer. 


Update mode 

By default, transactions operate in read- 
write mode, allowing you to read and write 
data which is locked so that nobody else can 
update it at the same time. If you wish just 
to read what is in the database when you 
start a transaction, and it therefore does not 
matter what updates other users are 
currently making, you can specify that you 
wish a transaction to operate as a read-only 
transaction. 


User 

Any person whose job entails direct action 
with the system. Users can be categorized 
according to their role and responsibilities. 
See also Application user, Developer, System 
administrator. 


User interface 

The interaction between a user and the 
information system, and the technology 
used to organize that interaction. 


Value 


Value 
Used in phrases such as: 


The value of a variable 

The value of a parameter 

The value of a property 

The value returned by a method 


The value can be any object (entity or literal). 
Where the value of a variable (or parameter 
or property) is an entity, it can be said that 
the variable (parameter, property) references 
that entity. 
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"is-a" relationships, 5-7 


# 


#define, 8-8, 8-15 
#ifdef, 8-8 
#include, 8-8, 8-15 
#odb_header, 8-16 


+h files, 8-8 


A 


Access control, 2-3 


Activex 


code component, 2-2, 3-2 

Compound Document Architecture, 2-2 
control, 2-2, 3-1, 3-2 

structured storage, 2-2 


addProcedure, 7-3, 8-1, 8-9, 8-12, 11-10 
addProperty(), 11-7 


Application 
design, 12-4 
development environment, 2-6 
multiple development, 5-13 
ODQL and host language, 8-4 
system level methods, 4-16 
upgrade to, 3-3 
use of polymorphism, 5-30 
user, 2-4 


Arithmetic operators, 6-11 


Atomic literals, 4-7, 4-10, 4-11, 6-3, 6-6, 8-5, 
9-15 


Attributes 
composite attributes, 5-17 
defining, 5-2, 5-16 
instead of multiple inheritance, 5-10 
overloading, 5-17 
use of versus methods, 5-16 


Boolean, 8-3, 8-5 


Boolean operators, 6-12 
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break statement, 6-25 
buildClass, 7-3, 7-7, 8-9 
Bulk loading, 10-2 

Business objects, 5-2 
ByteSequence, 8-5, 8-7, 11-7 
byteSequenceCat(), 8-8 


C 


C and C++, 2-2, 2-5, 2-6, 4-14, 5-28, 6-1, 6-5, 


8-8, 8-12, 9-16 
C and C++ compilers, 8-8 


C API, 2-2, 2-5, 2-6, 2-7, 3-2, 6-1 


CF parameter, 9-5 
Character strings, 6-6 
checkLevel environment parameter, 11-2 


Class 
adding a new, 11-4 
building using ODQL, 9-11 
changes to, 11-3 
creating by copying, 11-4 
defining, 5-14, 5-19 
defining using ODQL, 9-8 
deleting, 11-5 
grouping into a class family, 5-12 
identifying, 5-2 
interface to, 5-16 
libraries, 2-6 
names, 4-3 
system-defined class, 4-5 
unqualified names, 6-2 
use of redefinition, 4-18 
user-defined class, 4-5, 8-5 


Class family 
access name, 9-5 
alias name, 9-5 
default, 6-2, 7-5, 8-12 
defining, 9-4 


Class family (Continued) 

grouping classes into, 5-12 

names, 4-3 

original name, 9-5 

references to objects in other families, 
44 

relationship with store, 4-3 

setting up class definitions, 9-12 

specification in defineClass command, 
9-9 

top level class, 44 


Class hierarchy, 44, 4-6, 4-15, 4-16, 4-17, 
5-29 
defining, 5-2, 5-6 
example, 5-15 
getting it right, 5-8 


Class-collection-level methods, 4-15 


Class-level 
methods, 4-15, 4-17, 6-21, 8-13 
properties, 4-9, 6-35, 9-9 


Client/Server 
computing, 2-2 
software architecture, 2-2 


Clustering, 10-12 
Collection-level methods, 6-21 


Collections 
adding and removing elements, 6-27 
average, 6-28 
combining, 6-28 
counting elements, 6-28 
eliminating duplicate elements, 6-31 
empty collection, 6-32 
grouping elements, 6-22 
managing, 4-16 
manipulation of, 6-26 
maximum, 6-28 
minimum, 6-28 
sorting, 6-29 
total, 6-28 
updating properties in-situ, 6-35 
using an iterator, 6-31 
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Collection-valued 
attributes, 5-20 
properties, 5-5 


Collection-valued properties, 6-35 
Comparison operators, 6-12 
compileProcedure, 7-3, 7-7, 8-9 
Composite class, 44, 4-6, 4-7, 4-18 
Compound Documents, 2-2 
Conditional execution, 6-15 
Conventions used in this guide, 1-3 
createIndex(), 5-31 

createStore system command, 9-2 


Custom control, 2-2, 3-1, 3-2 


D 


Data management services, 2-3 


Data type 
abstract data types, 5-19 
choice of, 5-18 


Database 
access, 6-17 
administration, 2-3 
bulk loading, 5-31 
design, 5-1, 12-7 
design process, 5-1 
loading the live database, 10-7 
modifying the structure of, 11-1 


planning the load operation, 10-2 


populating, 3-3, 10-1 
setting up, 9-1 


Date, 8-5 
Deadlock 


during interpreter execution, 7-8 


in execFile command, 7-8 


Decimal, 8-5 


defaultCF declaration, 6-2, 8-12 
defineClass, 7-3, 7-7, 8-9, 11-4 


defineProcedure, 7-3, 7-7, 8-1, 8-9, 8-12 


delete(), 4-7, 6-5, 6-6, 6-36 
deleteStore system command, 9-3 


Development 
environments, 3-2 
platforms, 3-2 
process, 3-1 


directAdd(), 6-27, 6-35 
directRemove(), 6-27, 6-35 
Distributed object services, 5-28 
dropIndex(), 5-31 

Dynamic ODQL, 3-3, 8-9, 8-10 


Embedded ODQL, 6-1, 6-33 
commands, 8-9 
declarations, 8-3 
macros, 8-11 
statements, 8-3 
variables, 8-3 
writing methods, 8-12 


end, 7-3, 7-7, 8-9 
Error handling, 7-8, 9-20 


Example ODQL class definition, 9-10 


Exclusive queries, 6-21 

execFile, 7-3, 7-7, 8-10, 11-4 
execute statement, 8-10 
extendStore system command, 9-3 


External functions, invoking, 8-2 
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Flow of control, 6-15 


G 


getAllClasses(), 6-37 
getAllFamilies(), 6-37 
getClass(), 6-37 
getClassName(), 6-37 
getDescription(), 6-37 
getFamilyName(), 6-37 
getInsToClass(), 6-37, 6-38 
getMaxInstanceSize(), 6-37 
getMethodInfo(), 6-37 
getMethodSource(), 5-14, 6-9, 6-37 
getPropInfo(), 6-37 
getPropNames(), 6-37 
Greater or equal, 6-12 
Greater than, 6-12 


grouping-expression, 6-11, 6-22 


H 


Host language, 4-14, 7-3, 8-1 


Host language preprocessor, 8-8, 8-15 


HTML, 3-1, 3-3 


if statement, 6-15, 8-3 


Inclusion 
inheritance, 5-7 
principle, 5-6 
Indexes 
defining, 5-31 
for properties, 5-23 


indexScan statement, 6-24 


Information management component, 5-26 


Inheritance 
avoiding ambiguities, 5-11 
multiple inheritance, 4-17, 5-9 


redefining an inherited method, 8-14 


Instance migration, avoiding, 5-8 


Instance-collection-level methods, 4-15 


Instance-level 
methods, 4-15, 4-17, 6-22, 8-13 
properties, 4-9, 6-33, 9-9 


Instances 
examples, 4-4 
managing, 4-16 
overview, 4-7 


Integer, 8-5 
Integer class, 6-2 
Interpreted ODQL, 6-1 


Interrupt processing, 7-5 
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Jasmine 
class hierarchy, 4-4, 4-6, 4-15, 4-16, 4-17 
design and development facilities, 2-5 
support for 
atomic literals, 4-11 
polymorphism, 5-29 
query, 5-7 
users of, 2-4 


Jasmine Studio, 2-6, 3-2 


L 


Less or equal, 6-12 

Less than, 6-12 

like(), 6-15 

listIndex(), 5-31 

listStore system command, 9-4 
Literal representation, 5-19 

Live data from other systems, 10-2 
load, 10-5, 10-13 

Locking and concurrency control, 2-3 


Logical database design, 5-1, 5-2 


M 


Many-to-many relationships, 5-20, 5-24 
maxInstanceSize, 11-6 


Methods 
adding new, 11-10 
changing the code of, 11-11 
changing the specification of, 11-10 
coding and compiling with ODQL, 9-13 


compiling using ODQL, 9-18 
deciding the target class for, 5-27 
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